@rezamirzapour/pod-sdk 1.0.7 → 1.0.9

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/dist/index.d.mts

@@ -131,6 +131,70 @@ declare class SsoService {
     getUserProfile(accessToken: string): Promise<PodResponse<SsoUserProfile>>;
 }
 
+/**
+ * Types for Captcha service
+ */
+interface GenerateCaptchaOptions {
+    /** Width of captcha image (default: 200) */
+    width?: number;
+    /** Height of captcha image (default: 80) */
+    height?: number;
+    /** Length of captcha code (default: 5) */
+    length?: number;
+    /** Type of captcha (e.g., 'numeric', 'alphanumeric') */
+    type?: string;
+    /** Output format: 'svg' or 'png' (default: 'svg') */
+    format?: 'svg' | 'png';
+    /** Add noise to image (default: true) */
+    noise?: boolean;
+    /** Background color (hex) */
+    bgColor?: string;
+    /** Font color (hex) */
+    fontColor?: string;
+    /** Font size */
+    fontSize?: number;
+}
+interface GenerateCaptchaResponse {
+    /** Unique identifier for this captcha */
+    captchaId: string;
+    /** Captcha image as data URI or SVG string */
+    image: string;
+    /** Expiration timestamp (Unix epoch) */
+    expiresAt: number;
+    /** Mime type of image */
+    mimeType: string;
+}
+interface CheckCaptchaOptions {
+    /** The captcha value entered by user */
+    captchaValue: string;
+}
+interface CheckCaptchaResponse {
+    /** Whether captcha is valid */
+    valid: boolean;
+    /** Optional message */
+    message?: string;
+}
+
+interface CaptchaServiceOptions {
+    baseUrl: string;
+    clientId: string;
+    accessToken: string;
+}
+declare class CaptchaService {
+    private http;
+    private clientId;
+    private accessToken;
+    constructor(options: CaptchaServiceOptions);
+    /**
+     * Get a new captcha image
+     */
+    get(options?: GenerateCaptchaOptions): Promise<PodResponse<GenerateCaptchaResponse>>;
+    /**
+     * Check if the entered captcha value is valid
+     */
+    check(captchaId: string, options: CheckCaptchaOptions): Promise<PodResponse<CheckCaptchaResponse>>;
+}
+
 interface SearchTimelineParamMetaQuery<T extends object = any> {
     field?: string;
     is?: string | number | boolean;
@@ -1793,38 +1857,263 @@ declare class PodspaceService {
     removeBookmark(hash: string, options?: PodspaceRequestOptions): Promise<PodspaceRestResponse<boolean>>;
 }
 
-interface PodFormItem {
-    id: number;
-    title?: string;
-    elements?: any[];
-    [key: string]: any;
-}
+type PodFormId = number | string;
+type PodFormJson = Record<string, any>;
+/** Request options accepted by PodForm methods. */
+type PodFormRequestOptions = RequestOptions;
+/** Standard response envelope returned by PodForm. */
 interface PodFormResponse<T = any> {
     hasError: boolean;
     message?: string;
     errorCode?: number;
     result?: T;
     referenceNumber?: string;
+    count?: number;
+    [key: string]: any;
+}
+/** Form returned by the `/forms` endpoints. */
+interface PodFormItem extends PodFormJson {
+    id: number;
+    hash?: string;
+    name?: string;
+    title?: string;
+    elements?: any[];
+    fields?: PodFormField[];
+}
+/** Field returned by or sent to a form endpoint. */
+interface PodFormField extends PodFormJson {
+    id?: number;
+    title?: string;
+    type?: string;
+    required?: boolean;
+    order?: number;
+}
+interface PodFormCreationDto extends PodFormJson {
+    name: string;
+    type: 'GENERAL' | 'SHOP' | 'EXAM' | string;
+    display: 'CLASSIC' | 'CARD' | string;
+    fields?: PodFormField[];
+}
+interface PodFormUpdateDto extends PodFormJson {
+    name?: string;
+    enabled?: boolean;
+    activate?: boolean;
+    state?: string;
+    fieldsRandomization?: boolean;
+    tags?: string[];
+}
+interface PodFormSettingsUpdateDto extends PodFormJson {
+    name?: string;
+    display?: 'CLASSIC' | 'CARD' | string;
+    enabled?: boolean;
+    activate?: boolean;
+    fieldsRandomization?: boolean;
+    tags?: string[];
+}
+interface PodFormListParams {
+    page?: number;
+    size?: number;
+    sortBy?: string;
+    ascending?: boolean;
+    name?: string;
+    ownership?: string;
+    status?: string;
+    technicalStatus?: string;
+    tags?: string[];
+    folderId?: number;
+    [key: string]: any;
+}
+interface PodFormGetParams {
+    lockForEdit?: boolean;
+}
+interface PodFormPreviewParams {
+    responseId?: number;
+    code?: string;
+    responseHash?: string;
+    userParams?: string;
+}
+interface PodFormResponseCreationDto extends PodFormJson {
+    responses?: PodFormJson[];
+    parentFieldIds?: number[];
+    seenFieldIds?: number[];
+    screen?: string;
+    cookies?: boolean;
+    userMetadata?: PodFormJson;
+    userResponseTimeMilliSeconds?: number;
+}
+interface PodFormResponseInitiationDto extends PodFormJson {
+    owner?: string;
+    responses: PodFormJson[];
+}
+interface PodFormResponseListParams {
+    page?: number;
+    size?: number;
+    ssoId?: number;
+    username?: string;
+    gradingStatus?: string;
+    scoreFrom?: number;
+    scoreTo?: number;
+    startDate?: string;
+    endDate?: string;
+    sortDirection?: string;
+    [key: string]: any;
+}
+interface PodFormPaymentListParams {
+    page?: number;
+    size?: number;
+    payed?: boolean;
+    ssoId?: number;
+    username?: string;
+    startDate?: string;
+    endDate?: string;
+    [key: string]: any;
+}
+interface PodFormTemplateDto extends PodFormJson {
+    name: string;
+    theme?: PodFormJson;
+}
+interface PodFormFolderDto extends PodFormJson {
+    name: string;
+    config?: PodFormJson;
+}
+interface PodFormOtpParams {
+    contact: string;
+}
+interface PodFormDownloadLinkParams {
+    fileHash: string;
+    formId?: number;
+    isTemporary?: boolean;
+}
+interface PodFormExportParams {
+    fileType?: string;
+    dataType?: string;
+    ssoId?: number;
+    username?: string;
+    isTemplate?: boolean;
+    startDate?: string;
+    endDate?: string;
 }
 
 interface PodFormServiceOptions {
+    /** API base URL, e.g. `https://podformapi.pod.ir`. */
     baseUrl: string;
-    apiToken: string;
+    /** POD SSO token sent as the `token` header. */
+    apiToken?: string;
     revalidate?: number | string;
+    http?: NextHttp;
 }
+/**
+ * Typed client for the official PodForm API (Swagger OAS 3, v2.0.5).
+ *
+ * The API authenticates with the `token` header. All methods keep the raw
+ * PodForm response envelope so callers can inspect `hasError` and metadata.
+ */
 declare class PodFormService {
-    private http;
-    private apiToken;
-    private revalidate;
+    private readonly http;
+    private readonly revalidate;
     constructor(options: PodFormServiceOptions);
+    private requestOptions;
+    private languageHeaders;
+    /** Retrieves a form by its numeric ID. Swagger: GET `/forms/{formId}`. */
+    getForm(formId: PodFormId, params?: PodFormGetParams, options?: PodFormRequestOptions): Promise<PodFormResponse<PodFormItem>>;
+    /** Backward-compatible alias for `getForm`. */
+    getPodformById(id: PodFormId, options?: PodFormRequestOptions): Promise<PodFormResponse<PodFormItem>>;
+    /** Lists forms with the filters supported by Swagger. */
+    getForms(params?: PodFormListParams, options?: PodFormRequestOptions): Promise<PodFormResponse<PodFormItem[]>>;
+    /** Creates a form. Swagger: POST `/forms`. */
+    createForm(data: PodFormCreationDto, language?: string, options?: PodFormRequestOptions): Promise<PodFormResponse<PodFormItem>>;
+    /** Updates a form. Swagger: PATCH `/forms/{formId}`. */
+    updateForm(formId: PodFormId, data: PodFormUpdateDto, options?: PodFormRequestOptions): Promise<PodFormResponse<PodFormItem>>;
+    /** Deletes a form (or moves it to trash). */
+    deleteForm(formId: PodFormId, params?: {
+        removeFromTrash?: boolean;
+    }, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Gets form settings. Swagger: GET `/forms/{formId}/settings`. */
+    getFormSettings(formId: PodFormId, lockForEdit?: boolean, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Updates form settings. */
+    updateFormSettings(formId: PodFormId, data: PodFormSettingsUpdateDto, params?: {
+        allowClearCache?: boolean;
+    }, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Adds a field to a form. */
+    addField(formId: PodFormId, field: PodFormField, language?: string, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Adds multiple fields to a form. */
+    addFields(formId: PodFormId, fields: PodFormField[], language?: string, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Updates one or more fields. */
+    updateFields(formId: PodFormId, fields: PodFormJson[], options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Deletes selected fields from a form. */
+    deleteFields(formId: PodFormId, fieldIds: Array<number | string>, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Gets a form preview by ID. */
+    getFormPreview(formId: PodFormId, params?: PodFormPreviewParams, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Gets a public form preview by hash. */
+    getFormPreviewByHash(formHash: string, params?: Omit<PodFormPreviewParams, 'responseId'>, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Generates the captcha associated with a public form. */
+    generateCaptcha(formHash: string, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Saves a response using the Swagger JSON contract. */
+    saveResponse(formHash: string, data: PodFormResponseCreationDto, params?: Record<string, any>, language?: string, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /**
+     * Backward-compatible response helper. The form identifier can be numeric
+     * or a hash; the payload is now sent as JSON per the official API.
+     */
+    sendForm<T extends Record<string, any>>(formHash: PodFormId, data: T, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Initiates a response before collecting field values. */
+    initiateResponse(formId: PodFormId, data: PodFormResponseInitiationDto, language?: string, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Retrieves responses for a form with filtering and pagination. */
+    getAllFormResponses(formId: PodFormId, params?: PodFormResponseListParams, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Retrieves responses by a public form hash. */
+    getAllFormResponsesByHash(formHash: string, params?: Pick<PodFormResponseListParams, 'page' | 'size'>, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Gets an individual response. */
+    getResponse(responseId: PodFormId, containsNonInputFields?: boolean, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Updates fields of an existing response. */
+    updateResponseFields(responseId: PodFormId, fields: PodFormJson[], options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Deletes selected/all responses for a form. */
+    deleteResponses(formId: PodFormId, data: PodFormJson | Array<number | string>, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Lists templates available to the current user. */
+    getTemplates(params?: {
+        page?: number;
+        size?: number;
+        templateOwnership?: string;
+    }, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Creates a template. */
+    createTemplate(data: PodFormTemplateDto, templateOwnership?: string, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Updates or deletes a template. */
+    updateTemplate(templateId: PodFormId, data: Partial<PodFormTemplateDto>, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    deleteTemplate(templateId: PodFormId, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Lists or creates folders. */
+    getFolders(params?: {
+        page?: number;
+        size?: number;
+        name?: string;
+        ownership?: string;
+    }, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    createFolder(data: PodFormFolderDto, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    updateFolder(folderId: PodFormId, data: Partial<PodFormFolderDto>, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    deleteFolder(folderId: PodFormId, removeFromTrash?: boolean, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Sends or validates a form OTP. */
+    sendOtp(formHash: string, params: PodFormOtpParams, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    validateOtp(formHash: string, params: PodFormOtpParams & {
+        code: string;
+    }, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Retrieves the authenticated PodForm user. */
+    getUser(options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    getUploadLink(options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    getDownloadLink(params: PodFormDownloadLinkParams, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Gets plans and the current user's plan. */
+    getPlans(params?: {
+        page?: number;
+        size?: number;
+    }, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    getUserPlan(options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Exports form responses using the official export endpoint. */
+    exportResponses(formId: PodFormId, params?: PodFormExportParams, options?: PodFormRequestOptions): Promise<PodFormResponse>;
+    /** Retrieves the statistical report for a form. */
+    getFormReport(formId: PodFormId, options?: PodFormRequestOptions): Promise<PodFormResponse>;
     /**
-     * Submits responses/answers to a POD Form.
-     */
-    sendForm<T extends Record<string, any>>(formId: number, data: T): Promise<PodFormResponse>;
-    /**
-     * Retrieves a form and its questions by ID.
+     * Escape hatch for any newly-added Swagger operation not yet represented by
+     * a convenience method. Authentication and base URL are still applied.
      */
-    getPodformById(id: number, options?: RequestOptions): Promise<PodFormResponse<PodFormItem>>;
+    request<T = PodFormResponse>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, options?: PodFormRequestOptions & {
+        body?: any;
+    }): Promise<T>;
 }
 
 interface SendSmsParams {
@@ -3077,6 +3366,7 @@ declare class IumsService {
 
 declare class PodSdk {
     readonly sso: SsoService;
+    readonly captcha: CaptchaService;
     readonly customPost: CustomPostService;
     readonly podspace: PodspaceService;
     readonly podform: PodFormService;
@@ -3137,4 +3427,4 @@ declare function resolvePodUrls(urls?: PodUrlsConfig, sandbox?: boolean): Requir
 declare function encodeBase64(str: string): string;
 declare function generatePodSignatureHeader(keyId: string, privateKeyPem?: string): Promise<string>;
 
-export { type AccessLevel, type AddCommentParams, type AddContentParams, type AddCustomPostParams, type AddCustomPostResponse, type AddProductParams, type ApiPageLink, type ApiPageList, type ApiSimplePageList, type ArchiveParams, type ArchiveProductParams, type BatchPublishParams, type BatchPublishProductParams, type BatchUnpublishParams, type BatchUnpublishProductParams, type Business, type CachePolicy, CmsDataFormatter, type CmsMetadata, CmsProductService, type CmsProductServiceOptions, type CmsRequestOptions, CmsService, type CmsServiceOptions, CmsTagService, type CmsTagServiceOptions, type CommentItem, type ContentBody, type CreateFolderParams, type CreateLinkParams, type CreateTagCategoryParams, type CreateTagTreeItemParams, type CreateUserGroupParams, type CreateWorkspaceParams, type CustomPostCrudConfig, CustomPostCrudService, type CustomPostItem, CustomPostService, type CustomPostServiceOptions, DEFAULT_POD_URLS, type DownloadFileParams, type DownloadImageParams, type DownloadThumbnailParams, type DownloadZipParams, type EditContentParams, type EditProductParams, type FileVersion, type FinalizeResumableParams, type FormattedGetContentResponse, type FormattedGetProductResponse, type FormattedProductSubject, type FormattedSubject, type GetBookmarksParams, type GetCategoriesParams, type GetCategoryResponse, type GetCommentListParams, type GetCommentsParams, type GetContentByEntityIdParams, type GetContentParams, type GetContentResponse, type GetCustomPostParams, type GetCustomPostResponse, type GetFolderChildrenParams, type GetInfOfGraduatedByGraduateDateResponse, type GetProductByEntityIdParams, type GetProductParams, type GetProductResponse, type GetReactionsParams, type GetSessionClassInCurrentDayResponse, type GetTagCategoriesResponse, type GetTagTreeParams, type GetTagTreeResponse, type GetUploadLinkParams, type HandshakeResponse, type IumsResponse, IumsService, type IumsServiceOptions, type LikeCommentParams, type LikePostParams, type MakePublicParams, type MetaContent, type Metadata, NotificationService, type NotificationServiceOptions, type PaginationParams, type PodFormItem, type PodFormResponse, PodFormService, type PodFormServiceOptions, type PodResponse, PodSdk, type PodSdkConfig, type PodUrlsConfig, PodspaceBookmarksService, type PodspaceBookmarksServiceOptions, PodspaceFilesService, type PodspaceFilesServiceOptions, PodspaceFoldersService, type PodspaceFoldersServiceOptions, PodspaceLinksService, type PodspaceLinksServiceOptions, PodspaceMeService, type PodspaceMeServiceOptions, PodspaceMetadataService, type PodspaceMetadataServiceOptions, type PodspaceRequestOptions, type PodspaceRestResponse, PodspaceResumableService, type PodspaceResumableServiceOptions, PodspaceService, type PodspaceServiceOptions, PodspaceSharesService, type PodspaceSharesServiceOptions, PodspaceTagsService, type PodspaceTagsServiceOptions, PodspaceTrashService, type PodspaceTrashServiceOptions, PodspaceUploadDownloadService, type PodspaceUploadDownloadServiceOptions, type PodspaceUploadResponse, type PodspaceUploadResult, type PodspaceUser, PodspaceUserGroupsService, type PodspaceUserGroupsServiceOptions, PodspaceWorkspacesService, type PodspaceWorkspacesServiceOptions, type ProductBody, type ProductItem, type ProductItemWithFormatted, type Rate, type ReplaceFileParams, type ResultItem, type ResultItemWithFormatted, SANDBOX_POD_URLS, type SearchFilesParams, type SearchTimelineByMetadataParam, type SearchTimelineParamMetaQuery, type SearchTimelineResponse, type SearchTimelineResultItem, type SendOtpOptions, type SendSmsParams, type SendSmsResponse, type SeoType, type Share, type ShareAccess, type ShareEntityParams, type ShareType, type SocialResponse, SocialService, type SocialServiceOptions, type SpaceEntity, type SpaceFile, type SpaceFolder, SsoService, type SsoServiceOptions, type SsoUserProfile, type Subject, type TagCategoryItem, type TagCategoryListParams, type TagTreeAncestorsParams, type TagTreeMetadata, type TagtreesType, type ThumbnailStatus, type TimelineResponse, type TimelineSearchBody, type TokenResponse, type UpdateCustomPostParams, type UpdateLinkParams, type UpdateTagCategoryParams, type UpdateTagTreeItemParams, type UpdateWorkspaceParams, type UploadFileParams, type UploadImageBase64Params, type UploadMultipleFilesParams, type UserGroup, type UserPlan, type UserPostInfo, type UserUsageReport, type VerifyResponse, type Workspace, type WorkspaceMember, createPodSdk, PodSdk as default, encodeBase64, generatePodSignatureHeader, resolvePodUrls };
+export { type AccessLevel, type AddCommentParams, type AddContentParams, type AddCustomPostParams, type AddCustomPostResponse, type AddProductParams, type ApiPageLink, type ApiPageList, type ApiSimplePageList, type ArchiveParams, type ArchiveProductParams, type BatchPublishParams, type BatchPublishProductParams, type BatchUnpublishParams, type BatchUnpublishProductParams, type Business, type CachePolicy, CaptchaService, type CaptchaServiceOptions, type CheckCaptchaOptions, type CheckCaptchaResponse, CmsDataFormatter, type CmsMetadata, CmsProductService, type CmsProductServiceOptions, type CmsRequestOptions, CmsService, type CmsServiceOptions, CmsTagService, type CmsTagServiceOptions, type CommentItem, type ContentBody, type CreateFolderParams, type CreateLinkParams, type CreateTagCategoryParams, type CreateTagTreeItemParams, type CreateUserGroupParams, type CreateWorkspaceParams, type CustomPostCrudConfig, CustomPostCrudService, type CustomPostItem, CustomPostService, type CustomPostServiceOptions, DEFAULT_POD_URLS, type DownloadFileParams, type DownloadImageParams, type DownloadThumbnailParams, type DownloadZipParams, type EditContentParams, type EditProductParams, type FileVersion, type FinalizeResumableParams, type FormattedGetContentResponse, type FormattedGetProductResponse, type FormattedProductSubject, type FormattedSubject, type GenerateCaptchaOptions, type GenerateCaptchaResponse, type GetBookmarksParams, type GetCategoriesParams, type GetCategoryResponse, type GetCommentListParams, type GetCommentsParams, type GetContentByEntityIdParams, type GetContentParams, type GetContentResponse, type GetCustomPostParams, type GetCustomPostResponse, type GetFolderChildrenParams, type GetInfOfGraduatedByGraduateDateResponse, type GetProductByEntityIdParams, type GetProductParams, type GetProductResponse, type GetReactionsParams, type GetSessionClassInCurrentDayResponse, type GetTagCategoriesResponse, type GetTagTreeParams, type GetTagTreeResponse, type GetUploadLinkParams, type HandshakeResponse, type IumsResponse, IumsService, type IumsServiceOptions, type LikeCommentParams, type LikePostParams, type MakePublicParams, type MetaContent, type Metadata, NotificationService, type NotificationServiceOptions, type PaginationParams, type PodFormCreationDto, type PodFormDownloadLinkParams, type PodFormExportParams, type PodFormField, type PodFormFolderDto, type PodFormGetParams, type PodFormId, type PodFormItem, type PodFormJson, type PodFormListParams, type PodFormOtpParams, type PodFormPaymentListParams, type PodFormPreviewParams, type PodFormRequestOptions, type PodFormResponse, type PodFormResponseCreationDto, type PodFormResponseInitiationDto, type PodFormResponseListParams, PodFormService, type PodFormServiceOptions, type PodFormSettingsUpdateDto, type PodFormTemplateDto, type PodFormUpdateDto, type PodResponse, PodSdk, type PodSdkConfig, type PodUrlsConfig, PodspaceBookmarksService, type PodspaceBookmarksServiceOptions, PodspaceFilesService, type PodspaceFilesServiceOptions, PodspaceFoldersService, type PodspaceFoldersServiceOptions, PodspaceLinksService, type PodspaceLinksServiceOptions, PodspaceMeService, type PodspaceMeServiceOptions, PodspaceMetadataService, type PodspaceMetadataServiceOptions, type PodspaceRequestOptions, type PodspaceRestResponse, PodspaceResumableService, type PodspaceResumableServiceOptions, PodspaceService, type PodspaceServiceOptions, PodspaceSharesService, type PodspaceSharesServiceOptions, PodspaceTagsService, type PodspaceTagsServiceOptions, PodspaceTrashService, type PodspaceTrashServiceOptions, PodspaceUploadDownloadService, type PodspaceUploadDownloadServiceOptions, type PodspaceUploadResponse, type PodspaceUploadResult, type PodspaceUser, PodspaceUserGroupsService, type PodspaceUserGroupsServiceOptions, PodspaceWorkspacesService, type PodspaceWorkspacesServiceOptions, type ProductBody, type ProductItem, type ProductItemWithFormatted, type Rate, type ReplaceFileParams, type ResultItem, type ResultItemWithFormatted, SANDBOX_POD_URLS, type SearchFilesParams, type SearchTimelineByMetadataParam, type SearchTimelineParamMetaQuery, type SearchTimelineResponse, type SearchTimelineResultItem, type SendOtpOptions, type SendSmsParams, type SendSmsResponse, type SeoType, type Share, type ShareAccess, type ShareEntityParams, type ShareType, type SocialResponse, SocialService, type SocialServiceOptions, type SpaceEntity, type SpaceFile, type SpaceFolder, SsoService, type SsoServiceOptions, type SsoUserProfile, type Subject, type TagCategoryItem, type TagCategoryListParams, type TagTreeAncestorsParams, type TagTreeMetadata, type TagtreesType, type ThumbnailStatus, type TimelineResponse, type TimelineSearchBody, type TokenResponse, type UpdateCustomPostParams, type UpdateLinkParams, type UpdateTagCategoryParams, type UpdateTagTreeItemParams, type UpdateWorkspaceParams, type UploadFileParams, type UploadImageBase64Params, type UploadMultipleFilesParams, type UserGroup, type UserPlan, type UserPostInfo, type UserUsageReport, type VerifyResponse, type Workspace, type WorkspaceMember, createPodSdk, PodSdk as default, encodeBase64, generatePodSignatureHeader, resolvePodUrls };