@congminh1254/shopee-sdk
Version:
Shopee SDK maintaining by community
342 lines • 12.8 kB
JavaScript
import { BaseManager } from "./base.manager.js";
import { ShopeeFetch } from "../fetch.js";
/**
* MediaManager handles media upload operations for the Shopee API
*
* Provides methods for:
* - Image upload for various business scenarios
* - Video upload with multi-part upload support
* - Video upload status tracking
*/
export class MediaManager extends BaseManager {
constructor(config) {
super(config);
}
/**
* Upload images for specific business scenarios (e.g., returns)
*
* @param {UploadMediaImageParams} params - Parameters for uploading images
* @param {number} params.business - Business type (2 = Returns)
* @param {number} params.scene - Scene type (1 = Return Seller Self Arrange Pickup Proof)
* @param {Buffer | Array<Buffer>} params.images - Image files to upload
* @returns {Promise<UploadMediaImageResponse>} Response containing uploaded image information
*
* @example
* ```typescript
* const result = await sdk.media.uploadMediaImage({
* business: 2,
* scene: 1,
* images: Buffer.from('image-bytes')
* });
* console.log('Uploaded images:', result.response.image_list);
* ```
*
* **Restrictions:**
* - business = 2, scene = 1: Up to 3 images, max 10MB each, formats: JPG, JPEG, PNG
*
* @throws {Error} When the API request fails
*/
async uploadMediaImage(params) {
const response = await ShopeeFetch.fetch(this.config, "/media/upload_image", {
method: "POST",
body: params,
});
return response;
}
/**
* Upload multiple image files for general use
*
* @param {UploadImageParams} params - Parameters for uploading images
* @param {Buffer | Array<Buffer>} params.image - Image files (up to 9 images)
* @param {string} [params.scene] - Scene type ("normal" or "desc")
* @param {string} [params.ratio] - Image ratio ("1:1" or "3:4", whitelisted sellers only)
* @returns {Promise<UploadImageResponse>} Response containing uploaded image information
*
* @example
* ```typescript
* // Upload product images (square processing)
* const result = await sdk.media.uploadImage({
* image: [Buffer.from('image-1'), Buffer.from('image-2')],
* scene: 'normal',
* ratio: '1:1'
* });
*
* // Upload description images (no processing)
* const descResult = await sdk.media.uploadImage({
* image: Buffer.from('desc-image-bytes'),
* scene: 'desc'
* });
* ```
*
* **Image Requirements:**
* - Maximum: 9 images per request
* - Maximum size: 10MB per image
* - Formats: JPG, JPEG, PNG
* - Scene "normal": Image processed as square (recommended for item images)
* - Scene "desc": No processing (recommended for extended descriptions)
*
* @throws {Error} When the API request fails
*/
async uploadImage(params) {
const response = await ShopeeFetch.fetch(this.config, "/media_space/upload_image", {
method: "POST",
auth: true,
body: params,
});
return response;
}
/**
* Initiate a video upload session
*
* @param {InitVideoUploadParams} params - Parameters for initiating video upload
* @param {string} params.file_md5 - MD5 hash of the video file
* @param {number} params.file_size - Size of video file in bytes (max 30MB)
* @returns {Promise<InitVideoUploadResponse>} Response containing video_upload_id
*
* @example
* ```typescript
* const result = await sdk.media.initVideoUpload({
* file_md5: '2abf0b6e5ff90ff24437a0808f171a93',
* file_size: 1261876
* });
* const videoUploadId = result.response.video_upload_id;
* ```
*
* **Video Requirements:**
* - Duration: 10-60 seconds (inclusive)
* - Maximum size: 30MB
* - Must upload by parts after initialization
*
* @throws {Error} When the API request fails
* - error_file_size: File size is too large (max 30MB)
*/
async initVideoUpload(params) {
const response = await ShopeeFetch.fetch(this.config, "/media_space/init_video_upload", {
method: "POST",
auth: true,
body: params,
});
return response;
}
/**
* Upload a video file by parts
*
* @param {UploadVideoPartParams} params - Parameters for uploading video part
* @param {string} params.video_upload_id - Upload ID from initVideoUpload
* @param {number} params.part_seq - Sequence number starting from 0
* @param {string} params.content_md5 - MD5 hash of this part
* @param {Buffer} params.part_content - Content of this part
* @returns {Promise<UploadVideoPartResponse>} Response indicating upload success
*
* @example
* ```typescript
* // Upload video parts sequentially
* for (let i = 0; i < partCount; i++) {
* await sdk.media.uploadVideoPart({
* video_upload_id: videoUploadId,
* part_seq: i,
* content_md5: partMd5,
* part_content: Buffer.from('part-bytes')
* });
* }
* ```
*
* **Part Requirements:**
* - Part size: Exactly 4MB except for the last part
* - Must provide MD5 hash for each part
* - Upload parts sequentially starting from 0
*
* @throws {Error} When the API request fails
* - error_invalid_upload_id: Invalid upload_id
* - error_invalid_part_seq: Invalid part_seq
* - error_invalid_part_size: Invalid part_size
*/
async uploadVideoPart(params) {
const response = await ShopeeFetch.fetch(this.config, "/media_space/upload_video_part", {
method: "POST",
body: params,
});
return response;
}
/**
* Complete the video upload and start transcoding
*
* @param {CompleteVideoUploadParams} params - Parameters for completing video upload
* @param {string} params.video_upload_id - Upload ID from initVideoUpload
* @param {number[]} params.part_seq_list - List of all uploaded part sequences
* @param {object} params.report_data - Upload performance tracking data
* @param {number} params.report_data.upload_cost - Upload time in milliseconds
* @returns {Promise<CompleteVideoUploadResponse>} Response indicating completion
*
* @example
* ```typescript
* const startTime = Date.now();
* // ... upload all parts ...
* const uploadCost = Date.now() - startTime;
*
* await sdk.media.completeVideoUpload({
* video_upload_id: videoUploadId,
* part_seq_list: [0, 1, 2, 3],
* report_data: {
* upload_cost: uploadCost
* }
* });
* ```
*
* **Notes:**
* - Call this after all parts are uploaded successfully
* - Transcoding process begins after this call
* - Use getVideoUploadResult to check transcoding status
*
* @throws {Error} When the API request fails
* - error_invalid_upload_id: Invalid upload_id
* - error_already_completed: Upload already completed
*/
async completeVideoUpload(params) {
const response = await ShopeeFetch.fetch(this.config, "/media_space/complete_video_upload", {
method: "POST",
body: params,
});
return response;
}
/**
* Query the upload status and result of a video upload
*
* @param {GetVideoUploadResultParams} params - Parameters for querying video status
* @param {string} params.video_upload_id - Upload ID from initVideoUpload
* @returns {Promise<GetVideoUploadResultResponse>} Response containing upload status and video info
*
* @example
* ```typescript
* const result = await sdk.media.getVideoUploadResult({
* video_upload_id: videoUploadId
* });
*
* if (result.response.status === 'SUCCEEDED') {
* console.log('Video URL:', result.response.video_info.video_url_list);
* console.log('Duration:', result.response.video_info.duration);
* } else if (result.response.status === 'FAILED') {
* console.error('Upload failed:', result.response.message);
* }
* ```
*
* **Upload Status:**
* - INITIATED: Waiting for parts or complete_video_upload call
* - TRANSCODING: Transcoding the video file
* - SUCCEEDED: Transcoding completed, video ready to use
* - FAILED: Upload failed, check message for details
* - CANCELLED: Upload was cancelled
*
* @throws {Error} When the API request fails
* - error_invalid_upload_id: Invalid upload_id
*/
async getVideoUploadResult(params) {
const response = await ShopeeFetch.fetch(this.config, "/media_space/get_video_upload_result", {
method: "GET",
auth: true,
params,
});
return response;
}
/**
* Cancel a video upload session
*
* @param {CancelVideoUploadParams} params - Parameters for cancelling video upload
* @param {string} params.video_upload_id - Upload ID from initVideoUpload
* @returns {Promise<CancelVideoUploadResponse>} Response indicating cancellation
*
* @example
* ```typescript
* await sdk.media.cancelVideoUpload({
* video_upload_id: videoUploadId
* });
* console.log('Video upload cancelled');
* ```
*
* **Use Cases:**
* - Cancel upload on user request
* - Cancel failed upload to free resources
* - Cancel when upload takes too long
*
* @throws {Error} When the API request fails
* - error_invalid_upload_id: Invalid upload_id
* - error_already_completed: Upload already completed (cannot cancel)
*/
async cancelVideoUpload(params) {
const response = await ShopeeFetch.fetch(this.config, "/media_space/cancel_video_upload", {
method: "POST",
auth: true,
body: params,
});
return response;
}
/**
* Initiate a video upload session under the media module
*
* @param {InitMediaVideoUploadParams} params - Parameters for initiating video upload
* @returns {Promise<InitMediaVideoUploadResponse>} Response containing video_upload_id and part_size
*/
async initMediaVideoUpload(params) {
const response = await ShopeeFetch.fetch(this.config, "/media/init_video_upload", {
method: "POST",
auth: true,
body: params,
});
return response;
}
/**
* Upload a video part under the media module
*
* @param {UploadMediaVideoPartParams} params - Parameters for uploading video part
* @returns {Promise<UploadMediaVideoPartResponse>} Response indicating upload success
*/
async uploadMediaVideoPart(params) {
const response = await ShopeeFetch.fetch(this.config, "/media/upload_video_part", {
method: "POST",
body: params,
});
return response;
}
/**
* Complete the video upload under the media module
*
* @param {CompleteMediaVideoUploadParams} params - Parameters for completing video upload
* @returns {Promise<CompleteMediaVideoUploadResponse>} Response indicating completion
*/
async completeMediaVideoUpload(params) {
const response = await ShopeeFetch.fetch(this.config, "/media/complete_video_upload", {
method: "POST",
body: params,
});
return response;
}
/**
* Query the upload status and result of a video upload under the media module
*
* @param {GetMediaVideoUploadResultParams} params - Parameters for querying video status
* @returns {Promise<GetMediaVideoUploadResultResponse>} Response containing upload status and video info
*/
async getMediaVideoUploadResult(params) {
const response = await ShopeeFetch.fetch(this.config, "/media/get_video_upload_result", {
method: "GET",
auth: true,
params,
});
return response;
}
/**
* Cancel a video upload session under the media module
*
* @param {CancelMediaVideoUploadParams} params - Parameters for cancelling video upload
* @returns {Promise<CancelMediaVideoUploadResponse>} Response indicating cancellation
*/
async cancelMediaVideoUpload(params) {
const response = await ShopeeFetch.fetch(this.config, "/media/cancel_video_upload", {
method: "POST",
auth: true,
body: params,
});
return response;
}
}
//# sourceMappingURL=media.manager.js.map