@warriorteam/redai-zalo-sdk
Version:
Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account v3.0, ZNS with Full Type Safety, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, Promotion Service v3.0 with Multip
356 lines • 15 kB
TypeScript
import { ZaloClient } from "../clients/zalo-client";
import { ArticleRequest, ArticleNormalRequest, ArticleVideoRequest, ArticleResponse, ArticleProcessResponse, ArticleVerifyResponse, ArticleDetail, ArticleListRequest, ArticleListResponse, ArticleListItem, ArticleRemoveResponse, ArticleUpdateRequest, ArticleUpdateNormalRequest, ArticleUpdateVideoRequest, ArticleUpdateResponse, ArticleStatus, CommentStatus, BulkRemoveProgress, BulkRemoveOptions, BulkRemoveResult, BulkDetailProgress, BulkDetailOptions, BulkDetailResult } from "../types/article";
/**
* Service for handling Zalo Official Account Article Management APIs
*
* CONDITIONS FOR USING ZALO ARTICLE MANAGEMENT:
*
* 1. GENERAL CONDITIONS:
* - OA must have permission to create articles
* - Access token must have "manage_article" scope
* - OA must have active status and be verified
*
* 2. ARTICLE CREATION:
* - Title: required, max 150 characters
* - Author: required for normal articles, max 50 characters
* - Description: required, max 300 characters
* - Image size: max 1MB per image
* - Status: 'show' (publish immediately) or 'hide' (draft)
* - Comment: 'show' (allow comments) or 'hide' (disable comments)
*
* 3. CONTENT VALIDATION:
* - Normal articles: must have cover, body content, and author
* - Video articles: must have video_id and avatar
* - Body items: support text, image, video, and product types
* - Tracking links: must be valid URLs
*
* 4. LIMITS AND CONSTRAINTS:
* - Article list: max 10 items per request
* - Processing time: use token to check progress
* - Update frequency: reasonable intervals recommended
*/
export declare class ArticleService {
private readonly client;
private readonly endpoints;
constructor(client: ZaloClient);
/**
* Create normal article with rich content
* @param accessToken OA access token
* @param request Normal article information
* @returns Token for tracking creation progress
*/
createNormalArticle(accessToken: string, request: ArticleNormalRequest): Promise<ArticleResponse>;
/**
* Create video article
* @param accessToken OA access token
* @param request Video article information
* @returns Token for tracking creation progress
*/
createVideoArticle(accessToken: string, request: ArticleVideoRequest): Promise<ArticleResponse>;
/**
* Create article (automatically detect type)
* @param accessToken OA access token
* @param request Article information
* @returns Token for tracking creation progress
*/
createArticle(accessToken: string, request: ArticleRequest): Promise<ArticleResponse>;
/**
* Check article creation progress
* @param accessToken OA access token
* @param token Token from article creation response
* @returns Progress information
*/
checkArticleProcess(accessToken: string, token: string): Promise<ArticleProcessResponse>;
/**
* Verify article and get article ID
* @param accessToken OA access token
* @param token Token from article creation or update response
* @returns Article ID
*/
verifyArticle(accessToken: string, token: string): Promise<ArticleVerifyResponse>;
/**
* Get article details
* @param accessToken OA access token
* @param articleId Article ID
* @returns Article details
*/
getArticleDetail(accessToken: string, articleId: string): Promise<ArticleDetail>;
/**
* Get article list
* @param accessToken OA access token
* @param request List parameters
* @returns Article list
*/
getArticleList(accessToken: string, request: ArticleListRequest): Promise<ArticleListResponse>;
/**
* Get all articles by automatically fetching all pages
*
* @example
* ```typescript
* // Get all normal articles with progress tracking
* const result = await articleService.getAllArticles(accessToken, "normal", {
* batchSize: 50,
* maxArticles: 1000,
* onProgress: (progress) => {
* console.log(`Batch ${progress.currentBatch}: ${progress.totalFetched} articles fetched`);
* }
* });
*
* console.log(`Total: ${result.totalFetched} articles in ${result.totalBatches} batches`);
* console.log(`Has more: ${result.hasMore}`);
* ```
*
* @param accessToken OA access token
* @param type Article type ("normal" or "video")
* @param options Configuration options for fetching
* @returns All articles with pagination info
*/
getAllArticles(accessToken: string, type?: "normal" | "video", options?: {
/** Number of articles to fetch per request (default: 10, max: 10) */
batchSize?: number;
/** Maximum number of articles to fetch (default: 1000, 0 = no limit) */
maxArticles?: number;
/** Optional callback to track progress */
onProgress?: (progress: {
currentBatch: number;
totalFetched: number;
hasMore: boolean;
}) => void;
}): Promise<{
/** Array of all fetched articles */
articles: ArticleListItem[];
/** Total number of articles fetched */
totalFetched: number;
/** Number of API calls made */
totalBatches: number;
/** Whether there are more articles available */
hasMore: boolean;
}>;
/**
* Get all articles of both types (normal and video) combined
*
* @example
* ```typescript
* // Get all articles (both normal and video)
* const result = await articleService.getAllArticlesCombined(accessToken, {
* batchSize: 50,
* maxArticlesPerType: 500,
* onProgress: (progress) => {
* console.log(`${progress.type}: Batch ${progress.currentBatch}, Total: ${progress.totalFetched}`);
* }
* });
*
* console.log(`Total articles: ${result.totalFetched}`);
* console.log(`Normal articles: ${result.breakdown.normal.totalFetched}`);
* console.log(`Video articles: ${result.breakdown.video.totalFetched}`);
* ```
*
* @param accessToken OA access token
* @param options Configuration options for fetching
* @returns All articles (normal + video) with combined pagination info
*/
getAllArticlesCombined(accessToken: string, options?: {
/** Number of articles to fetch per request for each type (default: 10, max: 10) */
batchSize?: number;
/** Maximum number of articles to fetch per type (default: 500, 0 = no limit) */
maxArticlesPerType?: number;
/** Optional callback to track progress */
onProgress?: (progress: {
type: "normal" | "video";
currentBatch: number;
totalFetched: number;
hasMore: boolean;
}) => void;
}): Promise<{
/** Array of all fetched articles (normal + video) */
articles: ArticleListItem[];
/** Breakdown by type */
breakdown: {
normal: {
articles: ArticleListItem[];
totalFetched: number;
totalBatches: number;
hasMore: boolean;
};
video: {
articles: ArticleListItem[];
totalFetched: number;
totalBatches: number;
hasMore: boolean;
};
};
/** Total number of articles fetched */
totalFetched: number;
/** Total number of API calls made */
totalBatches: number;
}>;
/**
* Remove article
* @param accessToken OA access token
* @param articleId Article ID to remove
* @returns Removal result
*/
removeArticle(accessToken: string, articleId: string): Promise<ArticleRemoveResponse>;
/**
* Remove multiple articles in bulk (advanced function with progress tracking)
* @param accessToken OA access token
* @param articleIds Array of article IDs to remove
* @param options Options for bulk removal operation
* @param progressCallback Optional callback to track progress
* @returns Complete bulk removal result with detailed statistics
*
* This function automatically handles:
* - Batch processing to avoid overwhelming the API
* - Concurrent requests with configurable limits
* - Error handling for individual articles
* - Progress tracking and statistics
* - Retry mechanism for failed requests
*/
removeBulkArticles(accessToken: string, articleIds: string[], options?: BulkRemoveOptions, progressCallback?: (progress: BulkRemoveProgress) => void): Promise<BulkRemoveResult>;
/**
* Remove multiple articles in bulk with simple interface (no progress tracking)
* @param accessToken OA access token
* @param articleIds Array of article IDs to remove
* @param options Optional settings for bulk removal
* @returns Simple summary of bulk removal operation
*
* Simplified version of removeBulkArticles that returns just the summary statistics
*/
removeBulkArticlesSimple(accessToken: string, articleIds: string[], options?: BulkRemoveOptions): Promise<{
total_processed: number;
successful_count: number;
failed_count: number;
success_rate: number;
failed_articles?: string[];
}>;
/**
* Get all articles with full details (advanced function with progress tracking)
* @param accessToken OA access token
* @param type Article type ("normal", "video", or "both")
* @param options Options for bulk details fetch operation
* @param progressCallback Optional callback to track progress
* @returns Complete result with all articles and their full details
*
* This function automatically:
* 1. Fetches all articles list using getAllArticles() or getAllArticlesCombined()
* 2. Fetches detailed information for each article using getArticleDetail()
* 3. Handles batch processing and concurrency control
* 4. Provides detailed progress tracking and error handling
* 5. Returns both successful and failed results with statistics
*/
getAllArticlesWithDetails(accessToken: string, type?: "normal" | "video" | "both", options?: BulkDetailOptions, progressCallback?: (progress: BulkDetailProgress) => void): Promise<BulkDetailResult>;
/**
* Get all articles with full details - Simple interface (no progress tracking)
* @param accessToken OA access token
* @param type Article type ("normal", "video", or "both")
* @param options Optional settings for details fetch
* @returns Array of articles with full details
*
* Simplified version that returns just the articles with details array
*/
getAllArticlesWithDetailsSimple(accessToken: string, type?: "normal" | "video" | "both", options?: BulkDetailOptions): Promise<ArticleDetail[]>;
/**
* Create article and wait for completion - All-in-one method
* @param accessToken OA access token
* @param request Article information
* @param options Options for tracking and timeout
* @param progressCallback Optional callback to track progress
* @returns Article ID when creation is complete
*
* This method combines create + tracking + verification into one call:
* 1. Creates the article and gets token
* 2. Automatically tracks progress until completion
* 3. Returns the final article ID
* 4. Handles all errors and timeouts gracefully
*/
createArticleAndWaitForCompletion(accessToken: string, request: ArticleRequest, options?: {
/** Maximum time to wait for completion in milliseconds (default: 60000 = 1 minute) */
timeout?: number;
/** Interval between progress checks in milliseconds (default: 2000 = 2 seconds) */
checkInterval?: number;
/** Whether to return article details instead of just ID (default: false) */
returnDetails?: boolean;
}, progressCallback?: (progress: {
phase: 'creating' | 'processing' | 'verifying' | 'complete';
message: string;
token?: string;
article_id?: string;
elapsed_time: number;
}) => void): Promise<{
article_id: string;
token: string;
total_time: number;
article_details?: ArticleDetail;
}>;
/**
* Create article and wait for completion - Simple interface
* @param accessToken OA access token
* @param request Article information
* @param timeoutMs Optional timeout in milliseconds (default: 60000)
* @returns Article ID when creation is complete
*
* Simplified version that returns just the article ID
*/
createArticleAndGetId(accessToken: string, request: ArticleRequest, timeoutMs?: number): Promise<string>;
private handleArticleError;
/**
* Update normal article
* @param accessToken OA access token
* @param request Update information
* @returns Token for tracking update progress
*/
updateNormalArticle(accessToken: string, request: ArticleUpdateNormalRequest): Promise<ArticleUpdateResponse>;
/**
* Update video article
* @param accessToken OA access token
* @param request Update information
* @returns Token for tracking update progress
*/
updateVideoArticle(accessToken: string, request: ArticleUpdateVideoRequest): Promise<ArticleUpdateResponse>;
/**
* Update article (automatically detect type)
* @param accessToken OA access token
* @param request Update information
* @returns Token for tracking update progress
*/
updateArticle(accessToken: string, request: ArticleUpdateRequest): Promise<ArticleUpdateResponse>;
/**
* Update article status only
* @param accessToken OA access token
* @param articleId Article ID to update
* @param status New status ('show' or 'hide')
* @param comment Optional comment status ('show' or 'hide')
* @returns Token for tracking update progress
*/
updateArticleStatus(accessToken: string, articleId: string, status: ArticleStatus, comment?: CommentStatus): Promise<ArticleUpdateResponse>;
/**
* Validate normal article creation request
*/
private validateNormalArticleRequest;
/**
* Validate video article creation request
*/
private validateVideoArticleRequest;
/**
* Validate article list request
*/
private validateArticleListRequest;
/**
* Validate normal article update request
*/
private validateUpdateNormalArticleRequest;
/**
* Validate video article update request
*/
private validateUpdateVideoArticleRequest;
/**
* Validate cover information
*/
private validateCover;
/**
* Validate body item
*/
private validateBodyItem;
private isValidTrackingLink;
}
//# sourceMappingURL=article.service.d.ts.map