@rezamirzapour/pod-sdk 1.0.5 → 1.0.7

package/README.md

@@ -31,7 +31,7 @@
 | **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. |
+| **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. |
@@ -604,9 +604,259 @@ export async function getPublishedPosts() {
 
 ---
 
+## 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. |
+
+---
+
 ## Other POD Microservices
 
-### 4. POD SSO (OTP Handshake with Web Crypto RSA Signature)
+### 1. POD SSO (OTP Handshake with Web Crypto RSA Signature)
 
 ```typescript
 // app/actions/auth.ts
@@ -649,28 +899,7 @@ export async function getProfile(accessToken: string) {
 
 ---
 
-### 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. Notification (SMS Delivery)
 
 ```typescript
 // app/actions/notify.ts
@@ -688,7 +917,7 @@ export async function sendSms(phoneNumber: string, text: string) {
 
 ---
 
-### 7. Social (Comments & Likes)
+### 3. Social (Comments & Likes)
 
 ```typescript
 // app/actions/social.ts
@@ -710,7 +939,7 @@ export async function likePost(postId: number) {
 
 ---
 
-### 8. IUMS (Identity & University Management Service)
+### 4. IUMS (Identity & University Management Service)
 
 ```typescript
 // app/actions/iums.ts