@hasna/connectors 0.0.1

package/connectors/connect-tiktok/src/api/reports.ts

@@ -0,0 +1,290 @@
+import type { TikTokClient } from './client';
+import type { ReportParams, ReportData, DataLevel, ReportDimension, ReportMetric, PaginatedData } from '../types';
+
+/**
+ * TikTok Reports API
+ * Access integrated reports and performance metrics
+ */
+export class ReportsApi {
+  constructor(private readonly client: TikTokClient) {}
+
+  /**
+   * Get integrated report
+   * GET /report/integrated/get/
+   */
+  async getIntegrated(params: ReportParams): Promise<PaginatedData<ReportData>> {
+    return this.client.get<PaginatedData<ReportData>>('/report/integrated/get/', {
+      advertiser_id: params.advertiser_id,
+      report_type: params.report_type || 'BASIC',
+      data_level: params.data_level,
+      dimensions: JSON.stringify(params.dimensions),
+      metrics: JSON.stringify(params.metrics),
+      start_date: params.start_date,
+      end_date: params.end_date,
+      lifetime: params.lifetime,
+      filtering: params.filtering ? JSON.stringify(params.filtering) : undefined,
+      page: params.page,
+      page_size: params.page_size,
+      order_field: params.order_field,
+      order_type: params.order_type,
+    });
+  }
+
+  /**
+   * Get campaign level report
+   */
+  async getCampaignReport(params: {
+    advertiser_id: string;
+    campaign_ids?: string[];
+    metrics: ReportMetric[];
+    start_date: string;
+    end_date: string;
+    dimensions?: ReportDimension[];
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<ReportData>> {
+    return this.getIntegrated({
+      advertiser_id: params.advertiser_id,
+      data_level: 'AUCTION_CAMPAIGN',
+      metrics: params.metrics,
+      dimensions: params.dimensions || ['campaign_id'],
+      start_date: params.start_date,
+      end_date: params.end_date,
+      filtering: params.campaign_ids ? { campaign_ids: params.campaign_ids } : undefined,
+      page: params.page,
+      page_size: params.page_size,
+    });
+  }
+
+  /**
+   * Get ad group level report
+   */
+  async getAdGroupReport(params: {
+    advertiser_id: string;
+    adgroup_ids?: string[];
+    campaign_ids?: string[];
+    metrics: ReportMetric[];
+    start_date: string;
+    end_date: string;
+    dimensions?: ReportDimension[];
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<ReportData>> {
+    return this.getIntegrated({
+      advertiser_id: params.advertiser_id,
+      data_level: 'AUCTION_ADGROUP',
+      metrics: params.metrics,
+      dimensions: params.dimensions || ['adgroup_id'],
+      start_date: params.start_date,
+      end_date: params.end_date,
+      filtering: {
+        adgroup_ids: params.adgroup_ids,
+        campaign_ids: params.campaign_ids,
+      },
+      page: params.page,
+      page_size: params.page_size,
+    });
+  }
+
+  /**
+   * Get ad level report
+   */
+  async getAdReport(params: {
+    advertiser_id: string;
+    ad_ids?: string[];
+    adgroup_ids?: string[];
+    campaign_ids?: string[];
+    metrics: ReportMetric[];
+    start_date: string;
+    end_date: string;
+    dimensions?: ReportDimension[];
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<ReportData>> {
+    return this.getIntegrated({
+      advertiser_id: params.advertiser_id,
+      data_level: 'AUCTION_AD',
+      metrics: params.metrics,
+      dimensions: params.dimensions || ['ad_id'],
+      start_date: params.start_date,
+      end_date: params.end_date,
+      filtering: {
+        ad_ids: params.ad_ids,
+        adgroup_ids: params.adgroup_ids,
+        campaign_ids: params.campaign_ids,
+      },
+      page: params.page,
+      page_size: params.page_size,
+    });
+  }
+
+  /**
+   * Get advertiser level summary
+   */
+  async getAdvertiserSummary(params: {
+    advertiser_id: string;
+    metrics: ReportMetric[];
+    start_date: string;
+    end_date: string;
+  }): Promise<ReportData> {
+    const response = await this.getIntegrated({
+      advertiser_id: params.advertiser_id,
+      data_level: 'AUCTION_ADVERTISER',
+      metrics: params.metrics,
+      dimensions: ['advertiser_id'],
+      start_date: params.start_date,
+      end_date: params.end_date,
+    });
+    return response.list[0] || { dimensions: {}, metrics: {} };
+  }
+
+  /**
+   * Get daily report with time dimension
+   */
+  async getDailyReport(params: {
+    advertiser_id: string;
+    data_level: DataLevel;
+    metrics: ReportMetric[];
+    start_date: string;
+    end_date: string;
+    filtering?: {
+      campaign_ids?: string[];
+      adgroup_ids?: string[];
+      ad_ids?: string[];
+    };
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<ReportData>> {
+    const baseDimension = params.data_level.toLowerCase().replace('auction_', '') + '_id';
+    return this.getIntegrated({
+      advertiser_id: params.advertiser_id,
+      data_level: params.data_level,
+      metrics: params.metrics,
+      dimensions: [baseDimension as ReportDimension, 'stat_time_day'],
+      start_date: params.start_date,
+      end_date: params.end_date,
+      filtering: params.filtering,
+      page: params.page,
+      page_size: params.page_size,
+    });
+  }
+
+  /**
+   * Get audience report with demographic breakdown
+   */
+  async getAudienceReport(params: {
+    advertiser_id: string;
+    data_level: DataLevel;
+    metrics: ReportMetric[];
+    start_date: string;
+    end_date: string;
+    dimensions: ('gender' | 'age' | 'country_code' | 'platform')[];
+    filtering?: {
+      campaign_ids?: string[];
+      adgroup_ids?: string[];
+      ad_ids?: string[];
+    };
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<ReportData>> {
+    return this.getIntegrated({
+      advertiser_id: params.advertiser_id,
+      report_type: 'AUDIENCE',
+      data_level: params.data_level,
+      metrics: params.metrics,
+      dimensions: params.dimensions as ReportDimension[],
+      start_date: params.start_date,
+      end_date: params.end_date,
+      filtering: params.filtering,
+      page: params.page,
+      page_size: params.page_size,
+    });
+  }
+
+  /**
+   * Get real-time report
+   * GET /report/real_time/get/
+   */
+  async getRealTime(params: {
+    advertiser_id: string;
+    data_level: DataLevel;
+    dimensions: ReportDimension[];
+    metrics: ReportMetric[];
+    filtering?: {
+      campaign_ids?: string[];
+      adgroup_ids?: string[];
+      ad_ids?: string[];
+    };
+  }): Promise<{ list: ReportData[] }> {
+    return this.client.get('/report/real_time/get/', {
+      advertiser_id: params.advertiser_id,
+      data_level: params.data_level,
+      dimensions: JSON.stringify(params.dimensions),
+      metrics: JSON.stringify(params.metrics),
+      filtering: params.filtering ? JSON.stringify(params.filtering) : undefined,
+    });
+  }
+
+  /**
+   * Create an async report task
+   * POST /report/task/create/
+   */
+  async createTask(params: {
+    advertiser_id: string;
+    report_type?: string;
+    data_level: DataLevel;
+    dimensions: ReportDimension[];
+    metrics: ReportMetric[];
+    start_date: string;
+    end_date: string;
+    filtering?: {
+      campaign_ids?: string[];
+      adgroup_ids?: string[];
+      ad_ids?: string[];
+    };
+    file_name?: string;
+  }): Promise<{ task_id: string }> {
+    return this.client.post('/report/task/create/', {
+      advertiser_id: params.advertiser_id,
+      report_type: params.report_type || 'BASIC',
+      data_level: params.data_level,
+      dimensions: params.dimensions,
+      metrics: params.metrics,
+      start_date: params.start_date,
+      end_date: params.end_date,
+      filtering: params.filtering,
+      file_name: params.file_name,
+    });
+  }
+
+  /**
+   * Check async report task status
+   * GET /report/task/check/
+   */
+  async checkTask(advertiserId: string, taskId: string): Promise<{
+    task_id: string;
+    status: 'QUEUING' | 'PROCESSING' | 'SUCCESS' | 'FAILED';
+    file_path?: string;
+    file_size?: number;
+    message?: string;
+  }> {
+    return this.client.get('/report/task/check/', {
+      advertiser_id: advertiserId,
+      task_id: taskId,
+    });
+  }
+
+  /**
+   * Download async report file
+   * GET /report/task/download/
+   */
+  async downloadTask(advertiserId: string, taskId: string): Promise<{
+    file_path: string;
+    file_url: string;
+  }> {
+    return this.client.get('/report/task/download/', {
+      advertiser_id: advertiserId,
+      task_id: taskId,
+    });
+  }
+}

package/connectors/connect-tiktok/src/api/targeting.ts

@@ -0,0 +1,326 @@
+import type { TikTokClient } from './client';
+import type { Location, Interest, DeviceModel, Language, Carrier, TargetingCategory } from '../types';
+
+/**
+ * TikTok Targeting API
+ * Get available targeting options (locations, interests, devices, etc.)
+ */
+export class TargetingApi {
+  constructor(private readonly client: TikTokClient) {}
+
+  // ============================================
+  // Locations
+  // ============================================
+
+  /**
+   * Get location targeting options
+   * GET /targeting/recommend/get/
+   */
+  async getLocations(advertiserId: string, params?: {
+    objective_type?: string;
+    placement_type?: string;
+    location_type?: 'COUNTRY' | 'STATE' | 'CITY' | 'DMA' | 'REGION';
+  }): Promise<{ list: Location[] }> {
+    return this.client.get<{ list: Location[] }>('/targeting/recommend/get/', {
+      advertiser_id: advertiserId,
+      objective_type: params?.objective_type,
+      placement_type: params?.placement_type,
+      location_type: params?.location_type,
+    });
+  }
+
+  /**
+   * Search locations by name
+   * GET /region/search/
+   */
+  async searchLocations(
+    advertiserId: string,
+    query: string,
+    params?: {
+      objective_type?: string;
+      placement_type?: string;
+      level?: string;
+    }
+  ): Promise<{ regions: Location[] }> {
+    return this.client.get<{ regions: Location[] }>('/region/search/', {
+      advertiser_id: advertiserId,
+      search_term: query,
+      objective_type: params?.objective_type,
+      placement_type: params?.placement_type,
+      level: params?.level,
+    });
+  }
+
+  // ============================================
+  // Interests & Behaviors
+  // ============================================
+
+  /**
+   * Get interest categories
+   * GET /tool/interest_category/
+   */
+  async getInterestCategories(advertiserId: string, params?: {
+    version?: number;
+    placements?: string[];
+  }): Promise<{ interest_categories: TargetingCategory[] }> {
+    return this.client.get<{ interest_categories: TargetingCategory[] }>('/tool/interest_category/', {
+      advertiser_id: advertiserId,
+      version: params?.version,
+      placements: params?.placements,
+    });
+  }
+
+  /**
+   * Get interest keywords
+   * GET /tool/interest_keyword/recommend/
+   */
+  async getInterestKeywords(
+    advertiserId: string,
+    keyword: string,
+    params?: {
+      placements?: string[];
+      language?: string;
+    }
+  ): Promise<{ list: Interest[] }> {
+    return this.client.get<{ list: Interest[] }>('/tool/interest_keyword/recommend/', {
+      advertiser_id: advertiserId,
+      keyword,
+      placements: params?.placements,
+      language: params?.language,
+    });
+  }
+
+  /**
+   * Get action categories (behaviors)
+   * GET /tool/action_category/
+   */
+  async getActionCategories(advertiserId: string, params?: {
+    placements?: string[];
+  }): Promise<{ action_categories: TargetingCategory[] }> {
+    return this.client.get<{ action_categories: TargetingCategory[] }>('/tool/action_category/', {
+      advertiser_id: advertiserId,
+      placements: params?.placements,
+    });
+  }
+
+  // ============================================
+  // Demographics
+  // ============================================
+
+  /**
+   * Get age targeting options
+   * Returns available age groups for targeting
+   */
+  async getAgeOptions(): Promise<{
+    age_groups: Array<{
+      age_id: string;
+      age_name: string;
+      min_age?: number;
+      max_age?: number;
+    }>;
+  }> {
+    // Age groups are predefined by TikTok
+    return {
+      age_groups: [
+        { age_id: 'AGE_13_17', age_name: '13-17', min_age: 13, max_age: 17 },
+        { age_id: 'AGE_18_24', age_name: '18-24', min_age: 18, max_age: 24 },
+        { age_id: 'AGE_25_34', age_name: '25-34', min_age: 25, max_age: 34 },
+        { age_id: 'AGE_35_44', age_name: '35-44', min_age: 35, max_age: 44 },
+        { age_id: 'AGE_45_54', age_name: '45-54', min_age: 45, max_age: 54 },
+        { age_id: 'AGE_55_PLUS', age_name: '55+', min_age: 55 },
+      ],
+    };
+  }
+
+  /**
+   * Get gender targeting options
+   */
+  async getGenderOptions(): Promise<{
+    genders: Array<{
+      gender_id: string;
+      gender_name: string;
+    }>;
+  }> {
+    return {
+      genders: [
+        { gender_id: 'GENDER_UNLIMITED', gender_name: 'All' },
+        { gender_id: 'GENDER_MALE', gender_name: 'Male' },
+        { gender_id: 'GENDER_FEMALE', gender_name: 'Female' },
+      ],
+    };
+  }
+
+  // ============================================
+  // Languages
+  // ============================================
+
+  /**
+   * Get language targeting options
+   * GET /tool/language/
+   */
+  async getLanguages(advertiserId: string): Promise<{ languages: Language[] }> {
+    return this.client.get<{ languages: Language[] }>('/tool/language/', {
+      advertiser_id: advertiserId,
+    });
+  }
+
+  // ============================================
+  // Devices
+  // ============================================
+
+  /**
+   * Get device model targeting options
+   * GET /tool/device_model/
+   */
+  async getDeviceModels(advertiserId: string, params?: {
+    brand?: string;
+    os?: 'IOS' | 'ANDROID';
+  }): Promise<{ list: DeviceModel[] }> {
+    return this.client.get<{ list: DeviceModel[] }>('/tool/device_model/', {
+      advertiser_id: advertiserId,
+      brand: params?.brand,
+      os: params?.os,
+    });
+  }
+
+  /**
+   * Get operating system options
+   */
+  async getOperatingSystems(): Promise<{
+    operating_systems: Array<{
+      os_id: string;
+      os_name: string;
+    }>;
+  }> {
+    return {
+      operating_systems: [
+        { os_id: 'ANDROID', os_name: 'Android' },
+        { os_id: 'IOS', os_name: 'iOS' },
+      ],
+    };
+  }
+
+  /**
+   * Get network types
+   */
+  async getNetworkTypes(): Promise<{
+    network_types: Array<{
+      network_id: string;
+      network_name: string;
+    }>;
+  }> {
+    return {
+      network_types: [
+        { network_id: 'WIFI', network_name: 'WiFi' },
+        { network_id: '2G', network_name: '2G' },
+        { network_id: '3G', network_name: '3G' },
+        { network_id: '4G', network_name: '4G' },
+        { network_id: '5G', network_name: '5G' },
+      ],
+    };
+  }
+
+  // ============================================
+  // Carriers
+  // ============================================
+
+  /**
+   * Get carrier targeting options
+   * GET /tool/carrier/
+   */
+  async getCarriers(advertiserId: string, locationIds?: string[]): Promise<{ carriers: Carrier[] }> {
+    return this.client.get<{ carriers: Carrier[] }>('/tool/carrier/', {
+      advertiser_id: advertiserId,
+      location_ids: locationIds,
+    });
+  }
+
+  // ============================================
+  // Household & Spending
+  // ============================================
+
+  /**
+   * Get household income targeting options
+   */
+  async getHouseholdIncomeOptions(): Promise<{
+    household_incomes: Array<{
+      income_id: string;
+      income_name: string;
+    }>;
+  }> {
+    return {
+      household_incomes: [
+        { income_id: 'TOP_5_PCT', income_name: 'Top 5%' },
+        { income_id: 'TOP_10_PCT', income_name: 'Top 10%' },
+        { income_id: 'TOP_10_25_PCT', income_name: 'Top 10-25%' },
+        { income_id: 'TOP_25_50_PCT', income_name: 'Top 25-50%' },
+        { income_id: 'BOTTOM_50_PCT', income_name: 'Bottom 50%' },
+      ],
+    };
+  }
+
+  /**
+   * Get spending power targeting options
+   */
+  async getSpendingPowerOptions(): Promise<{
+    spending_powers: Array<{
+      spending_id: string;
+      spending_name: string;
+    }>;
+  }> {
+    return {
+      spending_powers: [
+        { spending_id: 'HIGH', spending_name: 'High' },
+        { spending_id: 'MEDIUM', spending_name: 'Medium' },
+        { spending_id: 'LOW', spending_name: 'Low' },
+      ],
+    };
+  }
+
+  // ============================================
+  // Audience Size Estimation
+  // ============================================
+
+  /**
+   * Get estimated audience size for targeting criteria
+   * GET /tool/targeting_reach/
+   */
+  async getReachEstimate(params: {
+    advertiser_id: string;
+    objective_type: string;
+    placement_type?: string;
+    location_ids?: string[];
+    age_groups?: string[];
+    gender?: string;
+    languages?: string[];
+    interest_category_ids?: string[];
+    interest_keyword_ids?: string[];
+    audience_ids?: string[];
+    excluded_audience_ids?: string[];
+    device_model_ids?: string[];
+    operating_systems?: string[];
+    network_types?: string[];
+  }): Promise<{
+    reach: {
+      lower_bound: number;
+      upper_bound: number;
+    };
+  }> {
+    return this.client.get('/tool/targeting_reach/', {
+      advertiser_id: params.advertiser_id,
+      objective_type: params.objective_type,
+      placement_type: params.placement_type,
+      location_ids: params.location_ids,
+      age_groups: params.age_groups,
+      gender: params.gender,
+      languages: params.languages,
+      interest_category_ids: params.interest_category_ids,
+      interest_keyword_ids: params.interest_keyword_ids,
+      audience_ids: params.audience_ids,
+      excluded_audience_ids: params.excluded_audience_ids,
+      device_model_ids: params.device_model_ids,
+      operating_systems: params.operating_systems,
+      network_types: params.network_types,
+    });
+  }
+}