polyv-live-api-sdk 1.0.2 → 1.0.5

package/dist/index.cjs

@@ -431,6 +431,117 @@ async function collectAll(fetcher, options = {}) {
   return allItems;
 }
 
+// src/utils/date-validation.ts
+var MAX_DATE_RANGE_DAYS = 60;
+var MAX_TIME_RANGE_MONTHS = 3;
+var MAX_AUDIENCE_TIME_RANGE_DAYS = 90;
+var DATE_FORMAT_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+function isValidDateFormat(dateStr) {
+  if (!dateStr || typeof dateStr !== "string") {
+    return false;
+  }
+  if (!DATE_FORMAT_REGEX.test(dateStr)) {
+    return false;
+  }
+  const date = new Date(dateStr);
+  if (isNaN(date.getTime())) {
+    return false;
+  }
+  const [year, month, day] = dateStr.split("-").map(Number);
+  return date.getFullYear() === year && date.getMonth() + 1 === month && date.getDate() === day;
+}
+function isStartDateBeforeEndDate(startDay, endDay) {
+  const startDate = new Date(startDay);
+  const endDate = new Date(endDay);
+  return startDate <= endDate;
+}
+function isStartTimeBeforeEndTime(startTime, endTime) {
+  return startTime <= endTime;
+}
+function isValidTimestamp(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return false;
+  }
+  return value > 9466848e5;
+}
+function validateDateRange(startDay, endDay, maxDays = MAX_DATE_RANGE_DAYS) {
+  if (!isStartDateBeforeEndDate(startDay, endDay)) {
+    return {
+      valid: false,
+      error: "startDay must be before or equal to endDay"
+    };
+  }
+  const startDate = new Date(startDay);
+  const endDate = new Date(endDay);
+  const diffTime = endDate.getTime() - startDate.getTime();
+  const diffDays = Math.ceil(diffTime / (1e3 * 60 * 60 * 24));
+  if (diffDays > maxDays) {
+    return {
+      valid: false,
+      error: `Date range cannot exceed ${maxDays} days`,
+      daysDiff: diffDays
+    };
+  }
+  return { valid: true, daysDiff: diffDays };
+}
+function validateTimestampRange(startTime, endTime, maxMonths = MAX_TIME_RANGE_MONTHS) {
+  if (!isStartTimeBeforeEndTime(startTime, endTime)) {
+    return {
+      valid: false,
+      error: "startTime must be before or equal to endTime"
+    };
+  }
+  const diffTime = endTime - startTime;
+  const diffDays = Math.ceil(diffTime / (1e3 * 60 * 60 * 24));
+  const maxDays = maxMonths * 31;
+  if (diffDays > maxDays) {
+    return {
+      valid: false,
+      error: `Time range cannot exceed ${maxMonths} months`,
+      daysDiff: diffDays
+    };
+  }
+  return { valid: true, daysDiff: diffDays };
+}
+function validate90DayTimestampRange(startTime, endTime) {
+  if (!isStartTimeBeforeEndTime(startTime, endTime)) {
+    return {
+      valid: false,
+      error: "startTime must be before or equal to endTime"
+    };
+  }
+  const diffTime = endTime - startTime;
+  const diffDays = Math.ceil(diffTime / (1e3 * 60 * 60 * 24));
+  if (diffDays > MAX_AUDIENCE_TIME_RANGE_DAYS) {
+    return {
+      valid: false,
+      error: `Time range cannot exceed ${MAX_AUDIENCE_TIME_RANGE_DAYS} days`,
+      daysDiff: diffDays
+    };
+  }
+  return { valid: true, daysDiff: diffDays };
+}
+function validateConcurrencyDateRange(startDate, endDate, maxDays = MAX_DATE_RANGE_DAYS) {
+  if (!isStartDateBeforeEndDate(startDate, endDate)) {
+    return {
+      valid: false,
+      error: "startDate must be before or equal to endDate"
+    };
+  }
+  const start = new Date(startDate);
+  const end = new Date(endDate);
+  const diffTime = end.getTime() - start.getTime();
+  const diffDays = Math.ceil(diffTime / (1e3 * 60 * 60 * 24));
+  if (diffDays > maxDays) {
+    return {
+      valid: false,
+      error: `Date range cannot exceed ${maxDays} days`,
+      daysDiff: diffDays
+    };
+  }
+  return { valid: true, daysDiff: diffDays };
+}
+
 // src/services/channel.service.ts
 var ChannelService = class {
   client;
@@ -1846,17 +1957,21 @@ var ChannelService = class {
    * await channelService.setRecordDefault('ch123456', 'file123');
    * ```
    */
-  async setRecordDefault(channelId, fileId) {
+  async setRecordDefault(channelId, fileId, listType) {
     if (!channelId || channelId.trim() === "") {
       throw PolyVValidationError.required("channelId");
     }
     if (!fileId || fileId.trim() === "") {
       throw PolyVValidationError.required("fileId");
     }
+    const params = { channelId, fileId };
+    if (listType) {
+      params.listType = listType;
+    }
     await this.client.httpClient.post(
       "/live/v3/channel/record/set-default",
       null,
-      { params: { channelId, fileId } }
+      { params }
     );
     return true;
   }
@@ -1970,6 +2085,38 @@ var ChannelService = class {
     );
     return response;
   }
+  /**
+   * Set playback setting (Story 9.7)
+   *
+   * Sets the playback settings for a channel.
+   * API: POST /live/v3/channel/playback/set-setting
+   *
+   * @param channelId - The channel ID
+   * @param options - Playback setting options
+   * @returns true if operation was successful
+   * @throws PolyVValidationError if channelId is empty
+   *
+   * @example
+   * ```typescript
+   * await channelService.setPlaybackSetting('ch123456', {
+   *   playbackEnabled: 'Y',
+   *   type: 'single',
+   *   origin: 'playback',
+   * });
+   * ```
+   */
+  async setPlaybackSetting(channelId, options) {
+    if (!channelId || channelId.trim() === "") {
+      throw PolyVValidationError.required("channelId");
+    }
+    const params = { channelId, ...options };
+    await this.client.httpClient.post(
+      "/live/v3/channel/playback/set-setting",
+      null,
+      { params }
+    );
+    return true;
+  }
   /**
    * Set playback sort
    *
@@ -2299,6 +2446,15 @@ var ChannelService = class {
     if (options.callbackUrl !== void 0) {
       params.callbackUrl = options.callbackUrl;
     }
+    if (options.autoConvert !== void 0) {
+      params.autoConvert = options.autoConvert;
+    }
+    if (options.mergeMp4 !== void 0) {
+      params.mergeMp4 = options.mergeMp4;
+    }
+    if (options.orderByCustom !== void 0) {
+      params.orderByCustom = options.orderByCustom;
+    }
     await this.client.httpClient.post(
       "/live/v3/channel/record/merge-async",
       null,
@@ -4035,6 +4191,44 @@ var ChannelService = class {
   // ============================================
   // Product APIs (Story 8-2)
   // ============================================
+  /**
+   * List channel products
+   *
+   * Lists products in a channel with pagination support.
+   *
+   * @param params - Query parameters including channelId (required)
+   * @returns Paginated product list
+   * @throws PolyVValidationError if channelId is missing
+   *
+   * @example
+   * ```typescript
+   * const result = await channelService.listChannelProducts({
+   *   channelId: 'ch123456',
+   *   pageNumber: 1,
+   *   pageSize: 20,
+   * });
+   * console.log(result.contents);
+   * ```
+   */
+  async listChannelProducts(params) {
+    if (!params.channelId || params.channelId.trim() === "") {
+      throw PolyVValidationError.required("channelId");
+    }
+    const queryParams = {
+      channelId: params.channelId
+    };
+    if (params.pageNumber !== void 0) {
+      queryParams.pageNumber = params.pageNumber;
+    }
+    if (params.pageSize !== void 0) {
+      queryParams.pageSize = params.pageSize;
+    }
+    const response = await this.client.httpClient.get(
+      "/live/v3/channel/product/list",
+      { params: queryParams }
+    );
+    return response;
+  }
   /**
    * Add channel product
    *
@@ -7432,7 +7626,8 @@ var WebService = class {
    * ```typescript
    * const result = await client.web.updateWhiteList({
    *   rank: 1,
-   *   code: '13800138000',
+   *   oldCode: '13800138000',
+   *   code: '13900139000',
    *   name: 'Updated Name',
    *   channelId: '123456',
    * });
@@ -7442,6 +7637,9 @@ var WebService = class {
     if (params.rank !== 1 && params.rank !== 2) {
       throw new PolyVValidationError("rank must be 1 or 2");
     }
+    if (!params.oldCode || params.oldCode.trim() === "") {
+      throw new PolyVValidationError("oldCode is required");
+    }
     if (!params.code || params.code.trim() === "") {
       throw new PolyVValidationError("code is required");
     }
@@ -7453,6 +7651,7 @@ var WebService = class {
     }
     const apiParams = {
       rank: params.rank,
+      oldCode: params.oldCode,
       code: params.code
     };
     if (params.name) {
@@ -7477,24 +7676,39 @@ var WebService = class {
    *
    * @example
    * ```typescript
+   * // Delete specific codes
    * const result = await client.web.deleteWhiteList({
    *   rank: 1,
+   *   isClear: 'N',
    *   codes: '13800138000,13800138001',
    *   channelId: '123456',
    * });
+   *
+   * // Clear all
+   * const result = await client.web.deleteWhiteList({
+   *   rank: 1,
+   *   isClear: 'Y',
+   *   channelId: '123456',
+   * });
    * ```
    */
   async deleteWhiteList(params) {
     if (params.rank !== 1 && params.rank !== 2) {
       throw new PolyVValidationError("rank must be 1 or 2");
     }
-    if (!params.codes || params.codes.trim() === "") {
-      throw new PolyVValidationError("codes is required");
+    if (!params.isClear) {
+      throw new PolyVValidationError("isClear is required");
+    }
+    if (params.isClear === "N" && (!params.codes || params.codes.trim() === "")) {
+      throw new PolyVValidationError("codes is required when isClear=N");
     }
     const apiParams = {
       rank: params.rank,
-      codes: params.codes
+      isClear: params.isClear
     };
+    if (params.codes) {
+      apiParams.code = params.codes;
+    }
     if (params.channelId) {
       apiParams.channelId = params.channelId;
     }
@@ -9399,6 +9613,112 @@ var PlayerService = class {
       }
     }
   }
+  // ============================================
+  // Channel Decorate APIs (Story 10.5)
+  // ============================================
+  /**
+   * Get channel decorate settings
+   * Query channel player decoration settings (watermark, warmup image, etc.)
+   *
+   * @param channelId - Channel ID
+   * @returns Channel decorate settings
+   *
+   * @example
+   * ```typescript
+   * const decorate = await client.player.getChannelDecorate(123456);
+   * console.log(decorate.player.watermarkEnabled);
+   * ```
+   */
+  async getChannelDecorate(channelId) {
+    this.validateChannelId(channelId);
+    const response = await this.client.httpClient.get(
+      "/live/v4/channel/decorate/get",
+      { params: { channelId } }
+    );
+    return response;
+  }
+  /**
+   * Update channel decorate settings
+   * Update channel player decoration settings (watermark, warmup image, etc.)
+   *
+   * @param channelId - Channel ID
+   * @param params - Channel decorate update parameters
+   * @returns true on success
+   *
+   * @example
+   * ```typescript
+   * await client.player.updateChannelDecorate(123456, {
+   *   watermarkEnabled: 'Y',
+   *   iconUrl: 'http://example.com/logo.png',
+   *   iconPosition: 'br',
+   *   logoOpacity: 0.8,
+   * });
+   * ```
+   */
+  async updateChannelDecorate(channelId, params) {
+    this.validateChannelId(channelId);
+    if (params.iconPosition !== void 0) {
+      this.validateLogoPosition(params.iconPosition);
+    }
+    if (params.logoOpacity !== void 0) {
+      this.validateDecorateOpacity(params.logoOpacity);
+    }
+    if (params.watermarkEnabled !== void 0) {
+      this.validateYNValue(params.watermarkEnabled, "watermarkEnabled");
+    }
+    if (params.warmUpEnabled !== void 0) {
+      this.validateYNValue(params.warmUpEnabled, "warmUpEnabled");
+    }
+    const playerBody = {};
+    if (params.watermarkEnabled !== void 0) {
+      playerBody.watermarkEnabled = params.watermarkEnabled;
+    }
+    if (params.iconUrl !== void 0) {
+      playerBody.iconUrl = params.iconUrl;
+    }
+    if (params.iconPosition !== void 0) {
+      playerBody.iconPosition = params.iconPosition;
+    }
+    if (params.logoOpacity !== void 0) {
+      playerBody.logoOpacity = params.logoOpacity;
+    }
+    if (params.iconLink !== void 0) {
+      playerBody.iconLink = params.iconLink;
+    }
+    if (params.warmUpEnabled !== void 0) {
+      playerBody.warmUpEnabled = params.warmUpEnabled;
+    }
+    if (params.warmUpImageUrl !== void 0) {
+      playerBody.warmUpImageUrl = params.warmUpImageUrl;
+    }
+    if (params.coverJumpUrl !== void 0) {
+      playerBody.coverJumpUrl = params.coverJumpUrl;
+    }
+    if (params.backgroundUrl !== void 0) {
+      playerBody.backgroundUrl = params.backgroundUrl;
+    }
+    if (params.basePV !== void 0) {
+      playerBody.basePV = params.basePV;
+    }
+    if (params.actualPV !== void 0) {
+      playerBody.actualPV = params.actualPV;
+    }
+    const body = { player: playerBody };
+    const response = await this.client.httpClient.post(
+      "/live/v4/channel/decorate/update",
+      body,
+      { params: { channelId } }
+    );
+    return response;
+  }
+  /**
+   * Validate decorate opacity (0-1)
+   */
+  validateDecorateOpacity(opacity) {
+    if (typeof opacity !== "number" || opacity < 0 || opacity > 1) {
+      throw new PolyVValidationError("logoOpacity must be a number between 0 and 1");
+    }
+  }
 };
 
 // src/services/other.service.ts
@@ -10860,7 +11180,9 @@ var V4ChannelService = class {
    * @returns Sessions list
    */
   async sessionList(params) {
-    this.validateChannelId(params.channelId);
+    if (params.channelId) {
+      this.validateChannelId(params.channelId);
+    }
     this.validatePaginationParams(params);
     const response = await this.client.httpClient.get(
       "/live/v4/channel/session/new/list",
@@ -12031,8 +12353,16 @@ var V4ChannelService = class {
    * Validate channel ID
    */
   validateChannelId(channelId) {
-    if (!channelId || channelId.trim() === "") {
-      throw new PolyVValidationError("channelId is required and cannot be empty", "channelId");
+    if (typeof channelId === "string") {
+      if (!channelId || channelId.trim() === "") {
+        throw new PolyVValidationError("channelId is required and cannot be empty", "channelId");
+      }
+    } else if (typeof channelId === "number") {
+      if (!channelId || channelId <= 0) {
+        throw new PolyVValidationError("channelId is required and must be a positive number", "channelId");
+      }
+    } else {
+      throw new PolyVValidationError("channelId must be a string or number", "channelId");
     }
   }
   /**
@@ -12816,7 +13146,7 @@ var V4UserService = class {
    */
   async listViewerLabels() {
     const response = await this.client.httpClient.get(
-      "/live/v4/user/viewer-record/label/list",
+      "/live/v4/user/viewer-label/list",
       {}
     );
     return response;
@@ -12896,8 +13226,11 @@ var V4UserService = class {
     this.validateRequiredString(params.viewerUnionId, "viewerUnionId");
     this.validateRequiredNumber(params.labelId, "labelId");
     await this.client.httpClient.post(
-      "/live/v4/user/viewer-record/label/add",
-      params
+      "/live/v4/user/viewer-label/add-viewers-label",
+      {
+        viewerUnionIds: [params.viewerUnionId],
+        labelIds: [params.labelId]
+      }
     );
   }
   /**
@@ -12917,8 +13250,11 @@ var V4UserService = class {
     this.validateRequiredString(params.viewerUnionId, "viewerUnionId");
     this.validateRequiredNumber(params.labelId, "labelId");
     await this.client.httpClient.post(
-      "/live/v4/user/viewer-record/label/delete-ref",
-      params
+      "/live/v4/user/viewer-label/remove-viewers-label",
+      {
+        viewerUnionIds: [params.viewerUnionId],
+        labelIds: [params.labelId]
+      }
     );
   }
   // ============================================
@@ -13932,6 +14268,47 @@ var V4UserService = class {
     return response;
   }
   // ============================================
+  // Story 13-3: Global Channel Settings APIs
+  // ============================================
+  /**
+   * Get global channel settings
+   *
+   * @returns Global channel settings
+   *
+   * @example
+   * ```typescript
+   * const settings = await client.v4User.getGlobalChannelSettings();
+   * ```
+   */
+  async getGlobalChannelSettings() {
+    const response = await this.client.httpClient.get(
+      "/live/v4/user/global-setting/switch/get",
+      {}
+    );
+    return response;
+  }
+  /**
+   * Update global channel settings
+   *
+   * @param params - Update parameters
+   *
+   * @example
+   * ```typescript
+   * await client.v4User.updateGlobalChannelSettings({
+   *   channelConcurrencesEnabled: 'Y',
+   *   donateEnabled: 'N',
+   *   coverImgType: 'contain',
+   * });
+   * ```
+   */
+  async updateGlobalChannelSettings(params) {
+    this.validateGlobalSettingsParams(params);
+    await this.client.httpClient.post(
+      "/live/v4/user/global-setting/switch/update",
+      params
+    );
+  }
+  // ============================================
   // Private Validation Helpers
   // ============================================
   /**
@@ -13961,6 +14338,31 @@ var V4UserService = class {
       throw new PolyVValidationError(`${fieldName} is required`, fieldName, value);
     }
   }
+  /**
+   * Validate global settings update parameters
+   */
+  validateGlobalSettingsParams(params) {
+    const booleanFields = [
+      "channelConcurrencesEnabled",
+      "timelyConvertEnabled",
+      "donateEnabled",
+      "rebirthAutoUploadEnabled",
+      "rebirthAutoConvertEnabled",
+      "pptCoveredEnabled",
+      "testModeButtonEnabled"
+    ];
+    for (const field of booleanFields) {
+      const value = params[field];
+      if (value !== void 0 && value !== "Y" && value !== "N") {
+        throw new PolyVValidationError(`${field} must be 'Y' or 'N'`, field, value);
+      }
+    }
+    if (params.coverImgType !== void 0) {
+      if (params.coverImgType !== "contain" && params.coverImgType !== "cover") {
+        throw new PolyVValidationError("coverImgType must be 'contain' or 'cover'", "coverImgType", params.coverImgType);
+      }
+    }
+  }
 };
 
 // src/services/v4/global.service.ts
@@ -14839,6 +15241,540 @@ var V4WebAppService = class {
   }
 };
 
+// src/services/statistics.service.ts
+var StatisticsService = class {
+  client;
+  /**
+   * Create a new StatisticsService instance
+   *
+   * @param client - The PolyVClient instance to use for API calls
+   */
+  constructor(client) {
+    this.client = client;
+  }
+  // ============================================
+  // Daily View Statistics API
+  // ============================================
+  /**
+   * Get daily view statistics
+   *
+   * Query daily view statistics for a channel within a date range.
+   * The date range cannot exceed 60 days.
+   *
+   * @param params - Query parameters
+   * @returns Daily view statistics response
+   * @throws {PolyVValidationError} When parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await client.statistics.getDailyViewStatistics({
+   *   channelId: '123456',
+   *   startDay: '2024-01-01',
+   *   endDay: '2024-01-31',
+   * });
+   * console.log(result.contents);
+   * ```
+   */
+  async getDailyViewStatistics(params) {
+    this.validateGetDailyViewStatisticsParams(params);
+    const response = await this.client.httpClient.get(
+      "/live/v3/channel/statistics/daily/summary",
+      { params }
+    );
+    return {
+      contents: response
+    };
+  }
+  // ============================================
+  // Private Validation Helpers
+  // ============================================
+  /**
+   * Validate parameters for getDailyViewStatistics
+   */
+  validateGetDailyViewStatisticsParams(params) {
+    if (!params.channelId || typeof params.channelId !== "string" || params.channelId.trim() === "") {
+      throw new PolyVValidationError(
+        "channelId is required and must be a non-empty string",
+        "channelId",
+        params.channelId
+      );
+    }
+    if (!params.startDay || !isValidDateFormat(params.startDay)) {
+      throw new PolyVValidationError(
+        "startDay is required and must be in yyyy-MM-dd format",
+        "startDay",
+        params.startDay
+      );
+    }
+    if (!params.endDay || !isValidDateFormat(params.endDay)) {
+      throw new PolyVValidationError(
+        "endDay is required and must be in yyyy-MM-dd format",
+        "endDay",
+        params.endDay
+      );
+    }
+    const rangeValidation = validateDateRange(params.startDay, params.endDay, MAX_DATE_RANGE_DAYS);
+    if (!rangeValidation.valid) {
+      throw new PolyVValidationError(
+        rangeValidation.error || "Invalid date range",
+        "dateRange",
+        { startDay: params.startDay, endDay: params.endDay, daysDiff: rangeValidation.daysDiff }
+      );
+    }
+  }
+  // ============================================
+  // Concurrency Data API (Story 10.2)
+  // ============================================
+  /**
+   * Get historical concurrency data
+   *
+   * Query historical concurrency data for a channel within a date range.
+   * The date range cannot exceed 60 days.
+   *
+   * @param params - Query parameters
+   * @returns Concurrency data response
+   * @throws {PolyVValidationError} When parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await client.statistics.getConcurrencyData({
+   *   channelId: '123456',
+   *   startDate: '2024-01-01',
+   *   endDate: '2024-01-31',
+   * });
+   * console.log(result.contents);
+   * ```
+   */
+  async getConcurrencyData(params) {
+    this.validateGetConcurrencyDataParams(params);
+    const response = await this.client.httpClient.get(
+      "/live/v3/channel/statistics/concurrence",
+      { params }
+    );
+    return {
+      contents: response
+    };
+  }
+  /**
+   * Validate parameters for getConcurrencyData
+   */
+  validateGetConcurrencyDataParams(params) {
+    if (!params.channelId || typeof params.channelId !== "string" || params.channelId.trim() === "") {
+      throw new PolyVValidationError(
+        "channelId is required and must be a non-empty string",
+        "channelId",
+        params.channelId
+      );
+    }
+    if (!params.startDate || !isValidDateFormat(params.startDate)) {
+      throw new PolyVValidationError(
+        "startDate is required and must be in yyyy-MM-dd format",
+        "startDate",
+        params.startDate
+      );
+    }
+    if (!params.endDate || !isValidDateFormat(params.endDate)) {
+      throw new PolyVValidationError(
+        "endDate is required and must be in yyyy-MM-dd format",
+        "endDate",
+        params.endDate
+      );
+    }
+    const rangeValidation = validateConcurrencyDateRange(params.startDate, params.endDate, MAX_DATE_RANGE_DAYS);
+    if (!rangeValidation.valid) {
+      throw new PolyVValidationError(
+        rangeValidation.error || "Invalid date range",
+        "dateRange",
+        { startDate: params.startDate, endDate: params.endDate, daysDiff: rangeValidation.daysDiff }
+      );
+    }
+  }
+  // ============================================
+  // Max Concurrent API (Story 10.2)
+  // ============================================
+  /**
+   * Get maximum historical concurrent viewers
+   *
+   * Query the maximum concurrent viewers for a channel within a time range.
+   * The time range cannot exceed 3 months.
+   *
+   * @param params - Query parameters
+   * @returns Max concurrent response
+   * @throws {PolyVValidationError} When parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await client.statistics.getMaxConcurrent({
+   *   channelId: '123456',
+   *   startTime: 1704067200000,
+   *   endTime: 1735689600000,
+   * });
+   * console.log(result.contents);
+   * ```
+   */
+  async getMaxConcurrent(params) {
+    this.validateGetMaxConcurrentParams(params);
+    const response = await this.client.httpClient.get(
+      "/live/v3/channel/statistics/get-max-history-concurrent",
+      { params }
+    );
+    return {
+      contents: response
+    };
+  }
+  /**
+   * Validate parameters for getMaxConcurrent
+   */
+  validateGetMaxConcurrentParams(params) {
+    if (!params.channelId || typeof params.channelId !== "string" || params.channelId.trim() === "") {
+      throw new PolyVValidationError(
+        "channelId is required and must be a non-empty string",
+        "channelId",
+        params.channelId
+      );
+    }
+    if (!isValidTimestamp(params.startTime)) {
+      throw new PolyVValidationError(
+        "startTime is required and must be a valid timestamp",
+        "startTime",
+        params.startTime
+      );
+    }
+    if (!isValidTimestamp(params.endTime)) {
+      throw new PolyVValidationError(
+        "endTime is required and must be a valid timestamp",
+        "endTime",
+        params.endTime
+      );
+    }
+    const rangeValidation = validateTimestampRange(params.startTime, params.endTime);
+    if (!rangeValidation.valid) {
+      throw new PolyVValidationError(
+        rangeValidation.error || "Invalid time range",
+        "timeRange",
+        { startTime: params.startTime, endTime: params.endTime, daysDiff: rangeValidation.daysDiff }
+      );
+    }
+  }
+  // ============================================
+  // Region Distribution API (Story 10.3)
+  // ============================================
+  /**
+   * Get region distribution
+   *
+   * Query the geographic distribution of viewers for a channel.
+   * The time range cannot exceed 90 days.
+   *
+   * @param params - Query parameters
+   * @returns Region distribution response
+   * @throws {PolyVValidationError} When parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await client.statistics.getRegionDistribution({
+   *   channelId: '123456',
+   *   startTime: 1648742400000,
+   *   endTime: 1651334399000,
+   *   type: 'province',
+   * });
+   * console.log(result.data);
+   * ```
+   */
+  async getRegionDistribution(params) {
+    this.validateGetRegionDistributionParams(params);
+    const requestParams = {
+      channelId: params.channelId,
+      startTime: params.startTime,
+      endTime: params.endTime
+    };
+    if (params.type) {
+      requestParams.type = params.type;
+    }
+    const response = await this.client.httpClient.get(
+      "/live/v4/channel/statistics/geo-summary-mc",
+      { params: requestParams }
+    );
+    return response;
+  }
+  /**
+   * Validate parameters for getRegionDistribution
+   */
+  validateGetRegionDistributionParams(params) {
+    if (!params.channelId || typeof params.channelId !== "string" || params.channelId.trim() === "") {
+      throw new PolyVValidationError(
+        "channelId is required and must be a non-empty string",
+        "channelId",
+        params.channelId
+      );
+    }
+    if (!isValidTimestamp(params.startTime)) {
+      throw new PolyVValidationError(
+        "startTime is required and must be a valid timestamp",
+        "startTime",
+        params.startTime
+      );
+    }
+    if (!isValidTimestamp(params.endTime)) {
+      throw new PolyVValidationError(
+        "endTime is required and must be a valid timestamp",
+        "endTime",
+        params.endTime
+      );
+    }
+    const rangeValidation = validate90DayTimestampRange(params.startTime, params.endTime);
+    if (!rangeValidation.valid) {
+      throw new PolyVValidationError(
+        rangeValidation.error || "Invalid time range",
+        "timeRange",
+        { startTime: params.startTime, endTime: params.endTime, daysDiff: rangeValidation.daysDiff }
+      );
+    }
+    if (params.type !== void 0) {
+      const validTypes = ["country", "province", "city"];
+      if (!validTypes.includes(params.type)) {
+        throw new PolyVValidationError(
+          "Type must be one of: country, province, city",
+          "type",
+          params.type
+        );
+      }
+    }
+  }
+  // ============================================
+  // Device Distribution API (Story 10.3)
+  // ============================================
+  /**
+   * Get device distribution
+   *
+   * Query the browser/device distribution of viewers for a channel.
+   * The time range cannot exceed 90 days.
+   *
+   * @param params - Query parameters
+   * @returns Device distribution response
+   * @throws {PolyVValidationError} When parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await client.statistics.getDeviceDistribution({
+   *   channelId: '123456',
+   *   startTime: 1651386101000,
+   *   endTime: 1652336501462,
+   * });
+   * console.log(result.data);
+   * ```
+   */
+  async getDeviceDistribution(params) {
+    this.validateGetDeviceDistributionParams(params);
+    const response = await this.client.httpClient.get(
+      "/live/v4/channel/statistics/browser-summary",
+      { params }
+    );
+    return response;
+  }
+  /**
+   * Validate parameters for getDeviceDistribution
+   */
+  validateGetDeviceDistributionParams(params) {
+    if (!params.channelId || typeof params.channelId !== "string" || params.channelId.trim() === "") {
+      throw new PolyVValidationError(
+        "channelId is required and must be a non-empty string",
+        "channelId",
+        params.channelId
+      );
+    }
+    if (!isValidTimestamp(params.startTime)) {
+      throw new PolyVValidationError(
+        "startTime is required and must be a valid timestamp",
+        "startTime",
+        params.startTime
+      );
+    }
+    if (!isValidTimestamp(params.endTime)) {
+      throw new PolyVValidationError(
+        "endTime is required and must be a valid timestamp",
+        "endTime",
+        params.endTime
+      );
+    }
+    const rangeValidation = validate90DayTimestampRange(params.startTime, params.endTime);
+    if (!rangeValidation.valid) {
+      throw new PolyVValidationError(
+        rangeValidation.error || "Invalid time range",
+        "timeRange",
+        { startTime: params.startTime, endTime: params.endTime, daysDiff: rangeValidation.daysDiff }
+      );
+    }
+  }
+  // ============================================
+  // Viewlog Export API (Story 10.4)
+  // ============================================
+  /**
+   * Get viewlog (viewing log) data
+   *
+   * Query viewing log data for a channel within a date range.
+   * The date range must be within the same month.
+   *
+   * @param params - Query parameters
+   * @returns Viewlog response with pagination
+   * @throws {PolyVValidationError} When parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await client.statistics.getViewlog({
+   *   channelId: '3151318',
+   *   startDate: '2024-01-01 00:00:00',
+   *   endDate: '2024-01-31 23:59:59',
+   * });
+   * console.log(result.contents);
+   * ```
+   */
+  async getViewlog(params) {
+    this.validateGetViewlogParams(params);
+    const requestParams = {
+      channelId: params.channelId,
+      startDate: params.startDate,
+      endDate: params.endDate,
+      pageSize: params.pageSize ?? 1e3
+    };
+    if (params.page !== void 0) {
+      requestParams.page = params.page;
+    }
+    if (params.watchType !== void 0) {
+      requestParams.watchType = params.watchType;
+    }
+    const response = await this.client.httpClient.get(
+      "/live/v3/user/statistics/viewlog",
+      { params: requestParams }
+    );
+    if (response && typeof response === "object" && "data" in response) {
+      const responseData = response;
+      if (responseData.data && typeof responseData.data === "object") {
+        return responseData.data;
+      }
+    }
+    return response;
+  }
+  /**
+   * Validate parameters for getViewlog
+   */
+  validateGetViewlogParams(params) {
+    if (!params.channelId || typeof params.channelId !== "string" || params.channelId.trim() === "") {
+      throw new PolyVValidationError(
+        "channelId is required and must be a non-empty string",
+        "channelId",
+        params.channelId
+      );
+    }
+    const dateTimeRegex = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+    if (!params.startDate || !dateTimeRegex.test(params.startDate)) {
+      throw new PolyVValidationError(
+        "startDate is required and must be in yyyy-MM-dd HH:mm:ss format",
+        "startDate",
+        params.startDate
+      );
+    }
+    if (!params.endDate || !dateTimeRegex.test(params.endDate)) {
+      throw new PolyVValidationError(
+        "endDate is required and must be in yyyy-MM-dd HH:mm:ss format",
+        "endDate",
+        params.endDate
+      );
+    }
+    const startMonth = params.startDate.substring(0, 7);
+    const endMonth = params.endDate.substring(0, 7);
+    if (startMonth !== endMonth) {
+      throw new PolyVValidationError(
+        "startDate and endDate must be in the same month",
+        "dateRange",
+        { startDate: params.startDate, endDate: params.endDate }
+      );
+    }
+    if (params.watchType !== void 0) {
+      const validWatchTypes = ["live", "vod"];
+      if (!validWatchTypes.includes(params.watchType)) {
+        throw new PolyVValidationError(
+          'watchType must be either "live" or "vod"',
+          "watchType",
+          params.watchType
+        );
+      }
+    }
+  }
+  // ============================================
+  // Session Stats Export API (Story 10.4)
+  // ============================================
+  /**
+   * Export session statistics report
+   *
+   * Export the session statistics report for a specific session.
+   * Returns a download URL for the report file.
+   *
+   * @param params - Query parameters
+   * @returns Export response with download URL
+   * @throws {PolyVValidationError} When parameters are invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await client.statistics.exportSessionStats({
+   *   channelId: '3151318',
+   *   sessionId: 'fv3ma84e63',
+   * });
+   * console.log(result.downloadUrl);
+   * ```
+   */
+  async exportSessionStats(params) {
+    this.validateExportSessionStatsParams(params);
+    const response = await this.client.httpClient.get(
+      "/live/v3/channel/session/stats/export",
+      { params }
+    );
+    if (response && typeof response === "object" && "data" in response) {
+      const responseData = response;
+      if (responseData.data && typeof responseData.data === "object") {
+        const innerData = responseData.data;
+        if (innerData.code && innerData.code !== 200) {
+          throw new Error(innerData.message || "API Error");
+        }
+        if ("downloadUrl" in innerData) {
+          return innerData;
+        }
+        if (typeof innerData.data === "string" && innerData.data) {
+          return { downloadUrl: innerData.data };
+        }
+      }
+    }
+    if (response && typeof response === "object" && "code" in response) {
+      const apiResponse = response;
+      if (apiResponse.code && apiResponse.code !== 200) {
+        throw new Error(String(apiResponse.message || "API Error"));
+      }
+      if (typeof apiResponse.data === "string" && apiResponse.data) {
+        return { downloadUrl: apiResponse.data };
+      }
+    }
+    return response;
+  }
+  /**
+   * Validate parameters for exportSessionStats
+   */
+  validateExportSessionStatsParams(params) {
+    if (!params.channelId || typeof params.channelId !== "string" || params.channelId.trim() === "") {
+      throw new PolyVValidationError(
+        "channelId is required and must be a non-empty string",
+        "channelId",
+        params.channelId
+      );
+    }
+    if (!params.sessionId || typeof params.sessionId !== "string" || params.sessionId.trim() === "") {
+      throw new PolyVValidationError(
+        "sessionId is required and must be a non-empty string",
+        "sessionId",
+        params.sessionId
+      );
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_CONFIG = {
   baseUrl: "https://api.polyv.net",
@@ -14862,6 +15798,10 @@ var PolyVClient = class {
    * Channel service for managing live channels
    */
   channel;
+  /**
+   * Statistics service for managing statistics operations
+   */
+  statistics;
   /**
    * Chat service for managing chat messages
    */
@@ -14961,6 +15901,7 @@ var PolyVClient = class {
     };
     this.httpClient = this.createHttpClient();
     this.channel = new ChannelService(this);
+    this.statistics = new StatisticsService(this);
     this.chat = new ChatService(this);
     this.liveInteraction = new LiveInteractionService(this);
     this.account = new AccountService(this);
@@ -15264,6 +16205,7 @@ exports.ChannelService = ChannelService;
 exports.ERROR_CATEGORIES = ERROR_CATEGORIES;
 exports.ERROR_MESSAGES = ERROR_MESSAGES;
 exports.HttpMethod = HttpMethod;
+exports.MAX_DATE_RANGE_DAYS = MAX_DATE_RANGE_DAYS;
 exports.PolyVAPIError = PolyVAPIError;
 exports.PolyVClient = PolyVClient;
 exports.PolyVError = PolyVError;
@@ -15288,8 +16230,11 @@ exports.isPolyVAPIError = isPolyVAPIError;
 exports.isPolyVError = isPolyVError;
 exports.isPolyVErrorCode = isPolyVErrorCode;
 exports.isPolyVValidationError = isPolyVValidationError;
+exports.isStartDateBeforeEndDate = isStartDateBeforeEndDate;
+exports.isValidDateFormat = isValidDateFormat;
 exports.isWebWorker = isWebWorker;
 exports.paginate = paginate;
 exports.sortParams = sortParams;
+exports.validateDateRange = validateDateRange;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map