@rezamirzapour/pod-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,470 @@
+# @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**.
+
+[![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 8 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.
+- 📦 **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 | 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. |
+
+---
+
+## 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: CMS & Generic 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`).
+
+### 1. Defining Types and Fetching CMS Articles with `getContent<T, P>`
+
+```tsx
+// app/news/page.tsx (Server Component)
+import { podSdk } from '@/lib/pod';
+
+// 1. Define the formatted structure of your CMS content type
+interface NewsArticle {
+  title: string;
+  coverImage: string; // Auto-transformed from hash to full Podspace CDN URL!
+  lead: string;
+  body: string;
+  publishDate: string;
+}
+
+// 2. Optional: Define normalized helper fields computed on the fly
+interface NewsNormalized {
+  summary: string;
+  readTimeEstimate: 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,
+    }
+  );
+
+  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 && (
+              <img
+                src={item.formatted.coverImage}
+                alt={item.formatted.title}
+                className="w-full h-48 object-cover rounded"
+              />
+            )}
+            <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>
+          </article>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### 2. Fetching Single Content by Entity ID: `getContentByEntityId<T>`
+
+```typescript
+// app/news/[id]/page.tsx
+import { podSdk } from '@/lib/pod';
+import { notFound } from 'next/navigation';
+
+interface ArticleDetail {
+  title: string;
+  content: string;
+  author: string;
+  coverImage: string;
+}
+
+export default async function NewsDetailPage({ params }: { params: { id: string } }) {
+  const res = await podSdk.cms.getContentByEntityId<ArticleDetail>({
+    entityId: Number(params.id),
+    contentTypeUniqueId: 'company_news',
+  });
+
+  const article = res.result?.[0];
+  if (!article) notFound();
+
+  return (
+    <main>
+      <h1>{article.formatted.title}</h1>
+      <p>By {article.formatted.author}</p>
+      <div dangerouslySetInnerHTML={{ __html: article.formatted.content }} />
+    </main>
+  );
+}
+```
+
+### 3. Adding and Editing CMS Content: `addContent<T>` & `editContent<T>`
+
+```typescript
+// app/actions/cms.ts
+'use server';
+
+import { podSdk } from '@/lib/pod';
+
+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,
+    },
+  });
+}
+```
+
+---
+
+## 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
+
+```typescript
+// lib/blog.ts
+import { podSdk } from '@/lib/pod';
+
+export interface BlogPostMeta {
+  slug: string;
+  title: string;
+  summary: string;
+  views: number;
+  publishedAt: string;
+}
+
+// 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. 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 in seconds:
+
+```typescript
+// lib/products.ts
+import { podSdk } from '@/lib/pod';
+
+export interface ProductData {
+  title: string;
+  sku: string;
+  price: number;
+  inStock: boolean;
+  category: string;
+  entityId?: number;
+}
+
+// Instantiate typed CRUD service for "product_item"
+export const productCrud = podSdk.createCrud<ProductData>({
+  name: 'product_entity',
+  type: 'commerce',
+  detailedType: 'gadgets',
+});
+```
+
+All methods on `productCrud` are fully generic:
+
+```typescript
+// app/actions/products.ts
+'use server';
+
+import { productCrud } from '@/lib/products';
+import { revalidatePath } from 'next/cache';
+
+// 1. Fetch all products
+export async function getProducts() {
+  const result = await productCrud.getAll();
+  return result.result.map((r) => r.item.metadata.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;
+}
+
+// 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;
+}
+
+// 4. Update product
+export async function updateProduct(entityId: number, data: ProductData) {
+  return productCrud.update(entityId, data);
+}
+
+// 5. Archive (soft-disable without deleting)
+export async function archiveProduct(entityId: number, data: ProductData) {
+  return productCrud.archive(entityId, data);
+}
+
+// 6. Delete permanently
+export async function deleteProduct(entityId: number) {
+  return productCrud.delete(entityId);
+}
+```
+
+---
+
+## Other POD Microservices
+
+### 3. 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) {
+  // 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');
+  }
+
+  // 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');
+  }
+
+  // Exchange authorization code for JWT tokens
+  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;
+}
+```
+
+---
+
+### 4. 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 };
+}
+```
+
+---
+
+### 5. 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,
+  });
+}
+```
+
+---
+
+### 6. 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);
+}
+```
+
+---
+
+### 7. 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)