@rezamirzapour/pod-sdk 1.0.5 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # @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**.
+> Unified, type-safe, enterprise-grade SDK for **POD Platform** microservices (CMS Content, CMS Product, SSO, Captcha, 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)
@@ -8,8 +8,9 @@
 
 ---
 
-## Features
-
+## Features
+
+- **Captcha Protection**: Generate configurable SVG/PNG challenges and validate user answers with a single, typed service.
 - 🌐 **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.
@@ -20,18 +21,19 @@
 - 🚀 **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
+---
+
+## 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. |
+| **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. |
+| **Captcha** | `sdk.captcha` | `captcha` | Generate SVG/PNG captcha images with configurable options and verify submitted values. |
+| **Podspace** | `sdk.podspace` | `public-apis` | Complete Cloud Storage: file/image uploads, resumable chunked uploads, folders, versions, share links, workspaces, trash, tags, & metadata. |
 | **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. |
@@ -58,9 +60,10 @@ 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
+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
+NEXT_PUBLIC_PODFORM_URL=https://podform.pod.ir
 
 # Sandbox Endpoints (Development & Staging)
 NEXT_PUBLIC_SANDBOX_CMS_URL=http://api.sandpod.ir/srv/cms-sandbox
@@ -69,8 +72,10 @@ 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.
+> [!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.
+
+Captcha requests use the resolved `apiPod` URL (`NEXT_PUBLIC_API_POD_URL` in production or `NEXT_PUBLIC_API_POD_SANDBOX_URL` when `sandbox: true`); there is no separate captcha URL setting.
 
 ---
 
@@ -604,9 +609,259 @@ export async function getPublishedPosts() {
 
 ---
 
-## Other POD Microservices
+## Deep Dive 5: Podspace Cloud Storage (Official Swagger API)
+
+The **Podspace** module provides complete enterprise integration with the official POD Podspace Cloud Storage service ([Swagger documentation: `podspace.sandpod.ir/api/docs`](http://podspace.sandpod.ir/api/docs)). It supports standard and resumable uploads, public/private files, dynamic CDN image transformations, folder hierarchy, file versioning, public share links, trash recovery, team workspaces, user groups, and custom metadata.
+
+### Sub-Services Architecture
+
+All Podspace operations are accessible via specialized, modular sub-services under `podSdk.podspace`:
+
+```typescript
+podSdk.podspace.files         // File details, rename, move, copy, search, versions, zip
+podSdk.podspace.folders       // Folder creation, nested paths, children, actions
+podSdk.podspace.resumable     // Chunked/large file upload (tus protocol: create, append, finalize)
+podSdk.podspace.links         // Public/password-protected shareable download links
+podSdk.podspace.shares        // Sharing files/folders with specific users & permissions
+podSdk.podspace.trash         // Recycle bin: list, restore, empty, auto-cleanup
+podSdk.podspace.bookmarks     // Starred / favorite files and folders
+podSdk.podspace.tags          // File & folder tagging
+podSdk.podspace.metadata      // Custom key-value metadata & descriptions
+podSdk.podspace.userGroups    // Group storage, member uploads & quota usage
+podSdk.podspace.workspaces    // Team workspaces & member roles
+podSdk.podspace.me            // User storage usage, plans, personal/chat folders
+```
+
+> [!TIP]
+> Commonly used methods (`uploadFile`, `downloadFile`, `getFileUrl`, `getImageUrl`, `getThumbnailUrl`, `createFolder`, `searchFiles`) are also directly available on `podSdk.podspace` for maximum developer convenience.
+
+---
+
+### Key Usage Examples
+
+#### 1. File Upload & CDN URLs (100% Backward Compatible)
+
+```typescript
+// app/actions/upload.ts
+'use server';
+
+import { podSdk } from '@/lib/pod';
+
+export async function uploadDocument(formData: FormData) {
+  // Supports both positional args (formData, path, isPublic) and options object
+  const res = await podSdk.podspace.uploadFile(formData, {
+    path: '/documents/invoices',
+    isPublic: true,
+  });
+
+  if (res.hasError) {
+    throw new Error(res.message || 'Upload failed');
+  }
+
+  const file = res.result;
+
+  // Resolve direct download URL
+  const downloadUrl = podSdk.podspace.getFileUrl(file.hash, true);
+
+  return {
+    hash: file.hash,
+    name: file.name,
+    size: file.size,
+    url: downloadUrl,
+  };
+}
+```
+
+#### 2. Image & Thumbnail CDN URL Helper
+
+```typescript
+// Helper functions generate instant CDN URLs without network calls:
+const fullImageUrl = podSdk.podspace.getImageUrl(imageHash, {
+  isPublic: true,
+  size: '1200x800',
+  quality: 85,
+  crop: true,
+});
+
+const thumbUrl = podSdk.podspace.getThumbnailUrl(imageHash, {
+  isPublic: true,
+  size: '150x150',
+});
+```
+
+#### 3. Base64 Image Upload
+
+```typescript
+// Upload image directly from a Base64 data URL
+const uploadRes = await podSdk.podspace.uploadImageBase64({
+  base64: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAE...',
+  filename: 'avatar.png',
+  path: '/avatars',
+  isPublic: true,
+});
+```
+
+#### 4. Resumable Chunked Upload (Large Files)
+
+For reliable multi-gigabyte uploads with pause/resume support:
+
+```typescript
+// Step 1: Initialize resumable session
+const session = await podSdk.podspace.resumable.create({
+  filename: 'presentation.mp4',
+  fileSize: totalBytes,
+  path: '/videos',
+  isPublic: false,
+});
+
+const uploadUrl = session.uploadUrl;
+
+// Step 2: Check current server offset if resuming
+const offset = await podSdk.podspace.resumable.getStatus(uploadUrl);
+
+// Step 3: Append chunks
+await podSdk.podspace.resumable.append({
+  uploadUrl,
+  offset,
+  chunk: chunkBuffer,
+});
+
+// Step 4: Finalize when all bytes are uploaded
+const completedFile = await podSdk.podspace.resumable.finalizeUpload(uploadUrl);
+```
+
+#### 5. Folder Hierarchy & Listing
+
+```typescript
+// Create a folder
+await podSdk.podspace.folders.createFolder({
+  name: 'Reports-2026',
+  path: '/finance',
+});
+
+// Recursively create nested directory paths
+await podSdk.podspace.folders.createDirectories('/finance/2026/Q1/receipts');
+
+// List folder contents with pagination
+const contents = await podSdk.podspace.folders.getFolderChildren({
+  path: '/finance/Reports-2026',
+  offset: 0,
+  size: 50,
+});
+```
+
+#### 6. Shareable Public / Password-Protected Links
+
+```typescript
+// Create an expiring, password-protected download link
+const linkRes = await podSdk.podspace.links.createLink(fileHash, {
+  type: 'DOWNLOAD',
+  password: 'SecurePassword123!',
+  expiresAt: Date.now() + 7 * 24 * 3600 * 1000, // 7 days
+});
+
+// Share with a specific user
+await podSdk.podspace.shares.shareWithUser(fileHash, {
+  username: 'john_doe',
+  permission: 'READ',
+});
+```
+
+#### 7. File Versions & Rollback
+
+```typescript
+// List previous versions of a file
+const versions = await podSdk.podspace.files.getFileVersions(fileHash);
+
+// Rollback to a specific historical version
+await podSdk.podspace.files.rollbackFileVersion(fileHash, versionId);
+```
+
+#### 8. Trash & Recycling
+
+```typescript
+// Move file or folder to trash
+await podSdk.podspace.files.trashEntity(fileHash);
+
+// List recycle bin
+const trashItems = await podSdk.podspace.trash.getTrashList({ size: 20 });
+
+// Restore or permanently delete
+await podSdk.podspace.trash.restore(fileHash);
+await podSdk.podspace.trash.deletePermanently(fileHash);
+```
+
+---
+
+### Podspace Methods Reference
+
+| Sub-Service | Method | HTTP | Path | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| **Upload / Download** | `uploadFile(formData, params)` | `POST` | `/api/files` | Upload single file with metadata. |
+| | `uploadMultipleFiles(formData, params)` | `POST` | `/api/files/batch` | Upload multiple files simultaneously. |
+| | `uploadImageBase64(params)` | `POST` | `/api/images/base64` | Upload base64 encoded image. |
+| | `replaceFile(hash, formData)` | `PUT` | `/api/files/{hash}` | Overwrite existing file content. |
+| | `uploadByLink(params)` | `POST` | `/api/files/link` | Download remote file into Podspace. |
+| | `downloadFile(hash, opts)` | `GET` | `/api/files/{hash}` | Download raw binary file. |
+| | `downloadImage(hash, opts)` | `GET` | `/api/images/{hash}` | Download transformed image. |
+| | `downloadThumbnail(hash, opts)` | `GET` | `/api/images/thumbnails/{hash}` | Download image thumbnail. |
+| | `downloadFilesAsZip(hashes)` | `POST` | `/api/files/zip` | Batch download files as a ZIP archive. |
+| | `getFileUrl(hash, isPublic)` | - | Client Helper | Generates direct file CDN link. |
+| | `getImageUrl(hash, opts)` | - | Client Helper | Generates transformed image CDN link. |
+| | `getThumbnailUrl(hash, opts)` | - | Client Helper | Generates thumbnail CDN link. |
+| **Files** | `getFileDetail(hash)` | `GET` | `/api/files/{hash}/metadata` | Fetch full metadata for file. |
+| | `getFileDetailByPath(path)` | `GET` | `/api/files/path` | Fetch metadata by absolute path. |
+| | `checkEntityExist(hash)` | `GET` | `/api/entities/{hash}/exist` | Check existence of file/folder. |
+| | `renameEntity(hash, newName)` | `PUT` | `/api/entities/{hash}/rename` | Rename file or folder. |
+| | `moveEntity(hash, targetPath)` | `PUT` | `/api/entities/{hash}/move` | Move file or folder. |
+| | `copyEntity(hash, targetPath)` | `POST` | `/api/entities/{hash}/copy` | Duplicate file or folder. |
+| | `trashEntity(hash)` | `DELETE` | `/api/entities/{hash}` | Move file/folder to trash. |
+| | `searchFiles(params)` | `GET` | `/api/files/search` | Search files by name, type, date, or tags. |
+| | `getFileVersions(hash)` | `GET` | `/api/files/{hash}/versions` | List all historical versions. |
+| | `rollbackFileVersion(hash, id)` | `POST` | `/api/files/{hash}/versions/{id}/rollback` | Rollback to specific version. |
+| | `compressToZip(params)` | `POST` | `/api/files/compress` | Compress files into a ZIP archive. |
+| | `extractZip(params)` | `POST` | `/api/files/extract` | Extract ZIP archive in Podspace. |
+| **Folders** | `createFolder(params)` | `POST` | `/api/folders` | Create a new folder. |
+| | `createDirectories(path)` | `POST` | `/api/folders/directories` | Create nested directory tree. |
+| | `getFolderChildren(params)` | `GET` | `/api/folders/{hash}/children` | List folder contents. |
+| | `getRecentFolders(params)` | `GET` | `/api/folders/recent` | List recently accessed folders. |
+| **Resumable** | `create(params)` | `POST` | `/api/files/resumable` | Initialize resumable upload. |
+| | `append(params)` | `PATCH` | `{uploadUrl}` | Upload chunk to offset. |
+| | `getStatus(uploadUrl)` | `HEAD` | `{uploadUrl}` | Get current uploaded byte offset. |
+| | `finalizeUpload(uploadUrl)` | `POST` | `{uploadUrl}/finalize` | Complete resumable upload. |
+| **Links** | `createLink(hash, params)` | `POST` | `/api/entities/{hash}/links` | Create shareable download link. |
+| | `getUserLinks(params)` | `GET` | `/api/links` | List all created links. |
+| | `revokeLink(linkHash)` | `DELETE` | `/api/links/{linkHash}` | Deactivate share link. |
+| **Shares** | `shareWithUser(hash, params)` | `POST` | `/api/entities/{hash}/shares` | Share with another user. |
+| | `makePublic(hash, isPublic)` | `PUT` | `/api/entities/{hash}/public` | Toggle public/private access. |
+| | `getSharedWithMe(params)` | `GET` | `/api/shares/shared-with-me` | List items shared with user. |
+| **Trash** | `getTrashList(params)` | `GET` | `/api/trash` | List items in recycle bin. |
+| | `restore(hash)` | `POST` | `/api/trash/{hash}/restore` | Restore file/folder. |
+| | `deletePermanently(hash)` | `DELETE` | `/api/trash/{hash}` | Permanently destroy file/folder. |
+| | `emptyTrash()` | `DELETE` | `/api/trash` | Empty entire recycle bin. |
+| **Bookmarks** | `getBookmarks(params)` | `GET` | `/api/bookmarks` | List starred files/folders. |
+| | `addBookmark(hash)` | `POST` | `/api/bookmarks/{hash}` | Star a file or folder. |
+| | `removeBookmark(hash)` | `DELETE` | `/api/bookmarks/{hash}` | Unstar a file or folder. |
+| **Tags** | `addTags(hash, tags)` | `POST` | `/api/entities/{hash}/tags` | Add tags to entity. |
+| | `getEntityTags(hash)` | `GET` | `/api/entities/{hash}/tags` | List entity tags. |
+| | `getEntitiesByTag(tag)` | `GET` | `/api/tags/{tag}/entities` | Search entities by tag. |
+| **Metadata** | `setMetadata(hash, metadata)` | `PUT` | `/api/entities/{hash}/metadata` | Set custom key-value metadata. |
+| | `setDescription(hash, desc)` | `PUT` | `/api/entities/{hash}/description` | Set entity description. |
+| **User Groups** | `createUserGroup(params)` | `POST` | `/api/user-groups` | Create user group. |
+| | `uploadToUserGroup(group, fd)`| `POST` | `/api/user-groups/{group}/files` | Upload file to user group. |
+| | `getUserGroupUsage(group)` | `GET` | `/api/user-groups/{group}/usage` | Get storage quota & usage. |
+| **Workspaces** | `createWorkspace(params)` | `POST` | `/api/workspaces` | Create team workspace. |
+| | `getWorkspaceMembers(id)` | `GET` | `/api/workspaces/{id}/members` | List workspace members. |
+| **Me** | `getUser()` | `GET` | `/api/users/me` | Current user profile. |
+| | `getUserUsageReport()` | `GET` | `/api/users/me/usage` | Total storage usage report. |
+| | `getPersonalFolder()` | `GET` | `/api/users/me/personal-folder` | Get or create root personal folder. |
+| | `getOrCreateChatFolder()` | `GET` | `/api/users/me/chat-folder` | Get or create chat attachments folder. |
 
-### 4. POD SSO (OTP Handshake with Web Crypto RSA Signature)
+---
+
+## Other POD Microservices
+
+### 1. POD SSO (OTP Handshake with Web Crypto RSA Signature)
 
 ```typescript
 // app/actions/auth.ts
@@ -644,33 +899,97 @@ export async function verifyOtp(authorization: string, phoneNumber: string, code
 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)
+}
+```
+
+---
+
+### 2. Captcha (Generate and Verify)
+
+The captcha service exposes the POD captcha API through `podSdk.captcha`. It creates a short-lived challenge image and checks the value entered by the user. Both calls return the SDK's standard `PodResponse<T>` shape (`hasError`, `result`, `message`, and `errorCode`).
+
+`Client-Id` and `Access-Token` headers are added automatically from `createPodSdk({ clientId, apiToken })`. Keep these credentials on the server and call captcha methods from a Server Action or Route Handler; do not expose the SDK token in a Client Component.
+
+#### Generate a captcha
+
+```typescript
+// app/actions/captcha.ts
+'use server';
+
+import { podSdk } from '@/lib/pod';
+
+export async function createCaptcha() {
+  const response = await podSdk.captcha.get({
+    width: 280,
+    height: 96,
+    length: 6,
+    type: 'alphanumeric',
+    format: 'png',
+    noise: true,
+    bgColor: '#ffffff',
+    fontColor: '#1f2937',
+    fontSize: 36,
+  });
+
+  if (response.hasError || !response.result) {
+    throw new Error(response.message || 'Captcha generation failed');
+  }
+
+  // `image` is a data URI or SVG string, depending on `format`.
+  return {
+    captchaId: response.result.captchaId,
+    image: response.result.image,
+    mimeType: response.result.mimeType,
+    expiresAt: response.result.expiresAt,
+  };
+}
+```
+
+#### Verify the submitted value
+
+```typescript
+import { podSdk } from '@/lib/pod';
+
+export async function verifyCaptcha(captchaId: string, captchaValue: string) {
+  const response = await podSdk.captcha.check(captchaId, { captchaValue });
+
+  if (response.hasError) {
+    return { valid: false, message: response.message || 'Captcha verification failed' };
+  }
+
+  return {
+    valid: response.result?.valid === true,
+    message: response.result?.message,
+  };
+}
+```
+
+#### Captcha methods
+
+| Method | HTTP | Path | Description |
+| :--- | :--- | :--- | :--- |
+| `get(options?)` | `POST` | `/api/core/captchas/generate` | Generate a captcha image. Options are sent as query parameters. |
+| `check(captchaId, { captchaValue })` | `POST` | `/api/core/captchas/check/{captchaId}` | Verify the value entered for a generated captcha. |
+
+`GenerateCaptchaOptions` supports the following fields:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `width` | `number` | `200` | Image width in pixels. |
+| `height` | `number` | `80` | Image height in pixels. |
+| `length` | `number` | `5` | Number of characters in the challenge. |
+| `type` | `string` | Server default | Challenge type, such as `numeric` or `alphanumeric`. |
+| `format` | `'svg' \| 'png'` | `'svg'` | Image output format. |
+| `noise` | `boolean` | `true` | Add visual noise to the image. |
+| `bgColor` | `string` | Server default | Background color in hex format. |
+| `fontColor` | `string` | Server default | Character color in hex format. |
+| `fontSize` | `number` | Server default | Character font size. |
+
+The generated response contains `captchaId`, `image`, `expiresAt`, and `mimeType`; `image` is returned as a data URI or SVG string. Always treat the challenge as temporary and request a new one after expiration or a failed attempt, according to your server-side policy.
+
+---
+
+### 3. Notification (SMS Delivery)
 
 ```typescript
 // app/actions/notify.ts
@@ -688,7 +1007,7 @@ export async function sendSms(phoneNumber: string, text: string) {
 
 ---
 
-### 7. Social (Comments & Likes)
+### 4. Social (Comments & Likes)
 
 ```typescript
 // app/actions/social.ts
@@ -710,7 +1029,7 @@ export async function likePost(postId: number) {
 
 ---
 
-### 8. IUMS (Identity & University Management Service)
+### 5. IUMS (Identity & University Management Service)
 
 ```typescript
 // app/actions/iums.ts