Competitive analysis

async function buildCompetitiveLandscape(client, brandId, period = 30) {
  const data = await client.getCompetitors(brandId, {
    period,
    relationship: 'SELF,DIRECT',
    limit: 100,
    sort: 'shareOfVoice',
    order: 'desc',
  });

  const self = data.competitors.find(
    (item) => item.relationship === 'SELF'
  );
  if (!self) throw new Error('SELF brand is absent from the selected scope');

  const competitors = data.competitors
    .filter((item) => item.relationship === 'DIRECT')
    .map((item) => ({
      id: item.id,
      name: item.name,
      mentions: item.totalMentions,
      shareOfVoice: item.shareOfVoice,
      shareOfVoiceGap: Number(
        (item.shareOfVoice - self.shareOfVoice).toFixed(2)
      ),
      averagePosition: item.avgPosition,
      sentiment: item.avgSentiment,
    }));

  return {
    period,
    self: {
      id: self.id,
      name: self.name,
      mentions: self.totalMentions,
      shareOfVoice: self.shareOfVoice,
    },
    competitors,
  };
}

def build_competitive_landscape(client, brand_id: str, period: int = 30) -> dict:
    data = client.get_competitors(
        brand_id, period=period, limit=100,
        sort='shareOfVoice', order='desc',
    )

    self_brand = next(
        (item for item in data['competitors']
         if item['relationship'] == 'SELF'),
        None,
    )
    if self_brand is None:
        raise ValueError('SELF brand is absent from the selected scope')

    competitors = [
        {
            'id': item['id'],
            'name': item['name'],
            'mentions': item['totalMentions'],
            'share_of_voice': item['shareOfVoice'],
            'share_of_voice_gap': round(
                item['shareOfVoice'] - self_brand['shareOfVoice'], 2
            ),
            'average_position': item['avgPosition'],
            'sentiment': item['avgSentiment'],
        }
        for item in data['competitors']
        if item['relationship'] == 'DIRECT'
    ]

    return {
        'period': period,
        'self': {
            'id': self_brand['id'],
            'name': self_brand['name'],
            'mentions': self_brand['totalMentions'],
            'share_of_voice': self_brand['shareOfVoice'],
        },
        'competitors': competitors,
    }

async function compareCompetitorEndpoints(
  client,
  brandId,
  competitorId,
  period = 30
) {
  const result = await client.getCompetitorEvolution(
    brandId,
    competitorId,
    { period }
  );
  const points = result.evolution;

  if (points.length < 2) {
    return { status: 'insufficient_data', points };
  }

  const first = points[0];
  const last = points.at(-1);
  const shareOfVoiceChange = Number(
    (last.shareOfVoice - first.shareOfVoice).toFixed(2)
  );

  return {
    status: 'observed',
    competitor: result.competitor,
    window: { start: first.date, end: last.date },
    shareOfVoice: {
      start: first.shareOfVoice,
      end: last.shareOfVoice,
      changePoints: shareOfVoiceChange,
      direction: shareOfVoiceChange > 0
        ? 'increased'
        : shareOfVoiceChange < 0
          ? 'decreased'
          : 'unchanged',
    },
    mentionChange: last.mentions - first.mentions,
    points,
  };
}

def compare_competitor_endpoints(
    client, brand_id: str, competitor_id: str, period: int = 30
) -> dict:
    result = client.get_competitor_evolution(
        brand_id, competitor_id, period=period
    )
    points = result['evolution']
    if len(points) < 2:
        return {'status': 'insufficient_data', 'points': points}

    first = points[0]
    last = points[-1]
    share_of_voice_change = round(
        last['shareOfVoice'] - first['shareOfVoice'], 2
    )
    direction = (
        'increased' if share_of_voice_change > 0
        else 'decreased' if share_of_voice_change < 0
        else 'unchanged'
    )

    return {
        'status': 'observed',
        'competitor': result['competitor'],
        'window': {'start': first['date'], 'end': last['date']},
        'share_of_voice': {
            'start': first['shareOfVoice'],
            'end': last['shareOfVoice'],
            'change_points': share_of_voice_change,
            'direction': direction,
        },
        'mention_change': last['mentions'] - first['mentions'],
        'points': points,
    }