@rezamirzapour/pod-sdk 1.0.7 → 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` | `public-apis` | Complete Cloud Storage: file/image uploads, resumable chunked uploads, folders, versions, share links, workspaces, trash, tags, & metadata. |
+| **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.
 
 ---
 
@@ -854,9 +859,9 @@ await podSdk.podspace.trash.deletePermanently(fileHash);
 
 ---
 
-## Other POD Microservices
-
-### 1. 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
@@ -894,12 +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;
-}
-```
-
----
-
-### 2. 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
@@ -917,7 +1007,7 @@ export async function sendSms(phoneNumber: string, text: string) {
 
 ---
 
-### 3. Social (Comments & Likes)
+### 4. Social (Comments & Likes)
 
 ```typescript
 // app/actions/social.ts
@@ -939,7 +1029,7 @@ export async function likePost(postId: number) {
 
 ---
 
-### 4. IUMS (Identity & University Management Service)
+### 5. IUMS (Identity & University Management Service)
 
 ```typescript
 // app/actions/iums.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rezamirzapour/pod-sdk",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "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",