@hasna/connectors 0.0.1

package/connectors/connect-snap/src/api/stats.ts

@@ -0,0 +1,305 @@
+import type { SnapClient } from './client';
+import type {
+  Stats,
+  StatsParams,
+  StatsResponse,
+  Granularity,
+  StatsBreakdown,
+} from '../types';
+
+/**
+ * Snapchat Stats API
+ * Get performance metrics and analytics
+ */
+export class StatsApi {
+  constructor(private readonly client: SnapClient) {}
+
+  /**
+   * Get stats for an ad account
+   */
+  async getAccountStats(adAccountId: string, params: StatsParams): Promise<Stats> {
+    const queryParams = this.buildStatsParams(params);
+    const response = await this.client.get<StatsResponse>(
+      `/adaccounts/${adAccountId}/stats`,
+      queryParams
+    );
+    return response.total_stats?.[0] || response.timeseries_stats?.[0] || ({} as Stats);
+  }
+
+  /**
+   * Get stats for a campaign
+   */
+  async getCampaignStats(campaignId: string, params: StatsParams): Promise<Stats> {
+    const queryParams = this.buildStatsParams(params);
+    const response = await this.client.get<StatsResponse>(
+      `/campaigns/${campaignId}/stats`,
+      queryParams
+    );
+    return response.total_stats?.[0] || response.timeseries_stats?.[0] || ({} as Stats);
+  }
+
+  /**
+   * Get stats for multiple campaigns
+   */
+  async getCampaignsStats(adAccountId: string, campaignIds: string[], params: StatsParams): Promise<Stats[]> {
+    const queryParams = this.buildStatsParams(params);
+    const response = await this.client.get<StatsResponse>(
+      `/adaccounts/${adAccountId}/campaigns/stats`,
+      {
+        ...queryParams,
+        campaign_id: campaignIds.join(','),
+      }
+    );
+    return response.total_stats || response.timeseries_stats || [];
+  }
+
+  /**
+   * Get stats for an ad squad
+   */
+  async getAdSquadStats(adSquadId: string, params: StatsParams): Promise<Stats> {
+    const queryParams = this.buildStatsParams(params);
+    const response = await this.client.get<StatsResponse>(
+      `/adsquads/${adSquadId}/stats`,
+      queryParams
+    );
+    return response.total_stats?.[0] || response.timeseries_stats?.[0] || ({} as Stats);
+  }
+
+  /**
+   * Get stats for multiple ad squads
+   */
+  async getAdSquadsStats(adAccountId: string, adSquadIds: string[], params: StatsParams): Promise<Stats[]> {
+    const queryParams = this.buildStatsParams(params);
+    const response = await this.client.get<StatsResponse>(
+      `/adaccounts/${adAccountId}/adsquads/stats`,
+      {
+        ...queryParams,
+        adsquad_id: adSquadIds.join(','),
+      }
+    );
+    return response.total_stats || response.timeseries_stats || [];
+  }
+
+  /**
+   * Get stats for an ad
+   */
+  async getAdStats(adId: string, params: StatsParams): Promise<Stats> {
+    const queryParams = this.buildStatsParams(params);
+    const response = await this.client.get<StatsResponse>(
+      `/ads/${adId}/stats`,
+      queryParams
+    );
+    return response.total_stats?.[0] || response.timeseries_stats?.[0] || ({} as Stats);
+  }
+
+  /**
+   * Get stats for multiple ads
+   */
+  async getAdsStats(adAccountId: string, adIds: string[], params: StatsParams): Promise<Stats[]> {
+    const queryParams = this.buildStatsParams(params);
+    const response = await this.client.get<StatsResponse>(
+      `/adaccounts/${adAccountId}/ads/stats`,
+      {
+        ...queryParams,
+        ad_id: adIds.join(','),
+      }
+    );
+    return response.total_stats || response.timeseries_stats || [];
+  }
+
+  /**
+   * Get stats for a pixel
+   */
+  async getPixelStats(pixelId: string, params: StatsParams): Promise<Stats> {
+    const queryParams = this.buildStatsParams(params);
+    const response = await this.client.get<StatsResponse>(
+      `/pixels/${pixelId}/stats`,
+      queryParams
+    );
+    return response.total_stats?.[0] || response.timeseries_stats?.[0] || ({} as Stats);
+  }
+
+  /**
+   * Build query parameters for stats requests
+   */
+  private buildStatsParams(params: StatsParams): Record<string, string | number | boolean | undefined> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {
+      start_time: params.start_time,
+      end_time: params.end_time,
+      granularity: params.granularity || 'DAY',
+    };
+
+    if (params.breakdown) {
+      queryParams.breakdown = params.breakdown;
+    }
+
+    if (params.fields?.length) {
+      queryParams.fields = params.fields.join(',');
+    }
+
+    if (params.swipe_up_attribution_window) {
+      queryParams.swipe_up_attribution_window = params.swipe_up_attribution_window;
+    }
+
+    if (params.view_attribution_window) {
+      queryParams.view_attribution_window = params.view_attribution_window;
+    }
+
+    if (params.conversion_source_types?.length) {
+      queryParams.conversion_source_types = params.conversion_source_types.join(',');
+    }
+
+    return queryParams;
+  }
+
+  /**
+   * Get daily stats for a campaign
+   */
+  async getDailyStats(
+    entityType: 'campaign' | 'adsquad' | 'ad',
+    entityId: string,
+    startDate: string,
+    endDate: string
+  ): Promise<Stats> {
+    const params: StatsParams = {
+      start_time: startDate,
+      end_time: endDate,
+      granularity: 'DAY',
+    };
+
+    switch (entityType) {
+      case 'campaign':
+        return this.getCampaignStats(entityId, params);
+      case 'adsquad':
+        return this.getAdSquadStats(entityId, params);
+      case 'ad':
+        return this.getAdStats(entityId, params);
+    }
+  }
+
+  /**
+   * Get hourly stats for a campaign
+   */
+  async getHourlyStats(
+    entityType: 'campaign' | 'adsquad' | 'ad',
+    entityId: string,
+    startDate: string,
+    endDate: string
+  ): Promise<Stats> {
+    const params: StatsParams = {
+      start_time: startDate,
+      end_time: endDate,
+      granularity: 'HOUR',
+    };
+
+    switch (entityType) {
+      case 'campaign':
+        return this.getCampaignStats(entityId, params);
+      case 'adsquad':
+        return this.getAdSquadStats(entityId, params);
+      case 'ad':
+        return this.getAdStats(entityId, params);
+    }
+  }
+
+  /**
+   * Get lifetime stats (total)
+   */
+  async getLifetimeStats(
+    entityType: 'campaign' | 'adsquad' | 'ad' | 'account',
+    entityId: string
+  ): Promise<Stats> {
+    // Use a very wide date range for lifetime stats
+    const params: StatsParams = {
+      start_time: '2016-01-01T00:00:00.000Z',
+      end_time: new Date().toISOString(),
+      granularity: 'TOTAL',
+    };
+
+    switch (entityType) {
+      case 'campaign':
+        return this.getCampaignStats(entityId, params);
+      case 'adsquad':
+        return this.getAdSquadStats(entityId, params);
+      case 'ad':
+        return this.getAdStats(entityId, params);
+      case 'account':
+        return this.getAccountStats(entityId, params);
+    }
+  }
+
+  /**
+   * Get stats with breakdown
+   */
+  async getStatsWithBreakdown(
+    entityType: 'campaign' | 'adsquad' | 'ad' | 'account',
+    entityId: string,
+    breakdown: StatsBreakdown,
+    startDate: string,
+    endDate: string,
+    granularity: Granularity = 'DAY'
+  ): Promise<Stats> {
+    const params: StatsParams = {
+      start_time: startDate,
+      end_time: endDate,
+      granularity,
+      breakdown,
+    };
+
+    switch (entityType) {
+      case 'campaign':
+        return this.getCampaignStats(entityId, params);
+      case 'adsquad':
+        return this.getAdSquadStats(entityId, params);
+      case 'ad':
+        return this.getAdStats(entityId, params);
+      case 'account':
+        return this.getAccountStats(entityId, params);
+    }
+  }
+
+  /**
+   * Get conversion stats with attribution windows
+   */
+  async getConversionStats(
+    entityType: 'campaign' | 'adsquad' | 'ad' | 'account',
+    entityId: string,
+    startDate: string,
+    endDate: string,
+    options?: {
+      swipeUpWindow?: '1_DAY' | '7_DAY' | '28_DAY';
+      viewWindow?: '1_HOUR' | '3_HOUR' | '6_HOUR' | '1_DAY' | '7_DAY' | '28_DAY';
+    }
+  ): Promise<Stats> {
+    const params: StatsParams = {
+      start_time: startDate,
+      end_time: endDate,
+      granularity: 'DAY',
+      swipe_up_attribution_window: options?.swipeUpWindow || '28_DAY',
+      view_attribution_window: options?.viewWindow || '1_DAY',
+      fields: [
+        'impressions',
+        'swipes',
+        'spend',
+        'conversion_purchases',
+        'conversion_purchases_value',
+        'conversion_sign_ups',
+        'conversion_add_carts',
+        'conversion_page_views',
+        'conversion_app_installs',
+        'conversion_app_opens',
+      ],
+    };
+
+    switch (entityType) {
+      case 'campaign':
+        return this.getCampaignStats(entityId, params);
+      case 'adsquad':
+        return this.getAdSquadStats(entityId, params);
+      case 'ad':
+        return this.getAdStats(entityId, params);
+      case 'account':
+        return this.getAccountStats(entityId, params);
+    }
+  }
+}

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

@@ -0,0 +1,255 @@
+import type { SnapClient } from './client';
+import type {
+  TargetingDimension,
+  TargetingResponse,
+  GeoTarget,
+  DemographicTarget,
+  DeviceTarget,
+} from '../types';
+
+/**
+ * Snapchat Targeting API
+ * Explore targeting options and get insights
+ */
+export class TargetingApi {
+  constructor(private readonly client: SnapClient) {}
+
+  /**
+   * Get all available targeting options for an ad account
+   */
+  async getOptions(adAccountId: string): Promise<TargetingDimension[]> {
+    const response = await this.client.get<TargetingResponse>(
+      `/adaccounts/${adAccountId}/targeting`
+    );
+    return response.targeting || [];
+  }
+
+  /**
+   * Get available geo targeting options (countries, regions, metros)
+   */
+  async getGeoOptions(adAccountId: string): Promise<{
+    countries: TargetingDimension[];
+    regions: TargetingDimension[];
+    metros: TargetingDimension[];
+  }> {
+    const [countries, regions, metros] = await Promise.all([
+      this.client.get<TargetingResponse>(`/targeting/geo/country`),
+      this.client.get<TargetingResponse>(`/targeting/geo/region`),
+      this.client.get<TargetingResponse>(`/targeting/geo/metro`),
+    ]);
+
+    return {
+      countries: countries.targeting || [],
+      regions: regions.targeting || [],
+      metros: metros.targeting || [],
+    };
+  }
+
+  /**
+   * Get available interest categories
+   */
+  async getInterests(): Promise<TargetingDimension[]> {
+    const response = await this.client.get<TargetingResponse>('/targeting/interests');
+    return response.targeting || [];
+  }
+
+  /**
+   * Search interest categories
+   */
+  async searchInterests(query: string): Promise<TargetingDimension[]> {
+    const response = await this.client.get<TargetingResponse>('/targeting/interests/search', {
+      query,
+    });
+    return response.targeting || [];
+  }
+
+  /**
+   * Get available device targeting options
+   */
+  async getDeviceOptions(): Promise<{
+    osTypes: string[];
+    carriers: TargetingDimension[];
+    deviceMakes: TargetingDimension[];
+  }> {
+    const [carriers, deviceMakes] = await Promise.all([
+      this.client.get<TargetingResponse>('/targeting/device/carrier'),
+      this.client.get<TargetingResponse>('/targeting/device/make'),
+    ]);
+
+    return {
+      osTypes: ['iOS', 'ANDROID', 'WEB'],
+      carriers: carriers.targeting || [],
+      deviceMakes: deviceMakes.targeting || [],
+    };
+  }
+
+  /**
+   * Get demographic targeting options
+   */
+  async getDemographicOptions(): Promise<{
+    ageGroups: string[];
+    genders: string[];
+    languages: TargetingDimension[];
+  }> {
+    const languages = await this.client.get<TargetingResponse>('/targeting/demographics/language');
+
+    return {
+      ageGroups: ['13-17', '18-20', '21-24', '25-34', '35-49', '50+'],
+      genders: ['MALE', 'FEMALE'],
+      languages: languages.targeting || [],
+    };
+  }
+
+  /**
+   * Estimate reach for targeting specification
+   */
+  async estimateReach(
+    adAccountId: string,
+    targeting: {
+      geos?: GeoTarget[];
+      demographics?: DemographicTarget[];
+      devices?: DeviceTarget[];
+      interests?: string[];
+      segments?: string[];
+    }
+  ): Promise<{
+    estimate_ready: boolean;
+    audience_size_minimum?: number;
+    audience_size_maximum?: number;
+  }> {
+    const response = await this.client.post<{
+      request_status: string;
+      targeting_reach: {
+        estimate_ready: boolean;
+        audience_size_minimum?: number;
+        audience_size_maximum?: number;
+      };
+    }>(
+      `/adaccounts/${adAccountId}/targeting/reach`,
+      { targeting_spec: targeting }
+    );
+
+    return response.targeting_reach;
+  }
+
+  /**
+   * Get location radius options for location targeting
+   */
+  async getLocationRadiusOptions(): Promise<{
+    units: string[];
+    minRadius: number;
+    maxRadius: number;
+  }> {
+    return {
+      units: ['MILES', 'KILOMETERS'],
+      minRadius: 0.5,
+      maxRadius: 50,
+    };
+  }
+
+  /**
+   * Search for postal codes
+   */
+  async searchPostalCodes(countryCode: string, query: string): Promise<string[]> {
+    const response = await this.client.get<{
+      request_status: string;
+      postal_codes: string[];
+    }>('/targeting/geo/postal_code/search', {
+      country_code: countryCode,
+      query,
+    });
+
+    return response.postal_codes || [];
+  }
+
+  /**
+   * Build a targeting specification
+   */
+  buildTargetingSpec(options: {
+    countries?: string[];
+    regions?: string[];
+    metros?: string[];
+    postalCodes?: string[];
+    ageGroups?: string[];
+    genders?: ('MALE' | 'FEMALE')[];
+    languages?: string[];
+    osTypes?: ('iOS' | 'ANDROID' | 'WEB')[];
+    connectionTypes?: ('WIFI' | 'CELL')[];
+    interests?: string[];
+    segments?: string[];
+    regulatedContent?: boolean;
+  }): {
+    geos?: GeoTarget[];
+    demographics?: DemographicTarget[];
+    devices?: DeviceTarget[];
+    interests?: string[];
+    segments?: string[];
+    regulated_content?: boolean;
+  } {
+    const spec: {
+      geos?: GeoTarget[];
+      demographics?: DemographicTarget[];
+      devices?: DeviceTarget[];
+      interests?: string[];
+      segments?: string[];
+      regulated_content?: boolean;
+    } = {};
+
+    // Build geo targeting
+    if (options.countries || options.regions || options.metros || options.postalCodes) {
+      spec.geos = [];
+
+      if (options.countries) {
+        for (const country of options.countries) {
+          spec.geos.push({ country_code: country });
+        }
+      }
+
+      if (options.regions) {
+        spec.geos.push({ region_id: options.regions });
+      }
+
+      if (options.metros) {
+        spec.geos.push({ metro_id: options.metros });
+      }
+
+      if (options.postalCodes) {
+        spec.geos.push({ postal_code: options.postalCodes });
+      }
+    }
+
+    // Build demographic targeting
+    if (options.ageGroups || options.genders || options.languages) {
+      spec.demographics = [{
+        age_groups: options.ageGroups,
+        genders: options.genders,
+        languages: options.languages,
+      }];
+    }
+
+    // Build device targeting
+    if (options.osTypes || options.connectionTypes) {
+      spec.devices = [{
+        os_type: options.osTypes,
+        connection_types: options.connectionTypes,
+      }];
+    }
+
+    // Add interests
+    if (options.interests?.length) {
+      spec.interests = options.interests;
+    }
+
+    // Add segments
+    if (options.segments?.length) {
+      spec.segments = options.segments;
+    }
+
+    // Regulated content flag
+    if (options.regulatedContent !== undefined) {
+      spec.regulated_content = options.regulatedContent;
+    }
+
+    return spec;
+  }
+}