SE Ranking

interface SERankingConfig {
  apiKey: string;   // SE Ranking API key — uses "Token <key>" bearer auth
}

integrations row:
  provider:   'se_ranking'
  api_key:    encrypt(apiKey)
  metadata:   {}

class SERankingTool {
  private baseUrl = 'https://api4.seranking.com';
 
  constructor(private apiKey: string) {}
 
  private headers() {
    return {
      Authorization: `Token ${this.apiKey}`,
      Accept:        'application/json',
    };
  }
 
  // ── Backlink Summary ─────────────────────────────────────────────────────────
 
  async getBacklinksSummary(domain: string): Promise<BacklinksSummaryResult> {
    const response = await axios.get(
      `${this.baseUrl}/research/backlinks/summary/`,
      {
        headers: this.headers(),
        params:  {
          domain,
          domain_type: 'domain',   // 'domain' | 'page' | 'subdomain'
        },
      },
    );
    return {
      domain,
      totalBacklinks:    response.data.total_backlinks,
      referringDomains:  response.data.referring_domains,
      referringIPs:      response.data.referring_ips,
      trustFlow:         response.data.trust_flow,
      citationFlow:      response.data.citation_flow,
      domainScore:       response.data.domain_trust_score,
      noFollowLinks:     response.data.nofollow_backlinks,
      doFollowLinks:     response.data.dofollow_backlinks,
    };
  }
 
  // ── Backlinks List ───────────────────────────────────────────────────────────
 
  async getBacklinks(options: {
    domain:     string;
    limit?:     number;
    offset?:    number;
    sortBy?:    'trust_flow' | 'citation_flow' | 'first_seen';
    doFollowOnly?: boolean;
  }): Promise<BacklinkRow[]> {
    const response = await axios.get(
      `${this.baseUrl}/research/backlinks/`,
      {
        headers: this.headers(),
        params: {
          domain:        options.domain,
          domain_type:   'domain',
          limit:         options.limit  ?? 50,
          offset:        options.offset ?? 0,
          sort_by:       options.sortBy ?? 'trust_flow',
          filter_dofollow: options.doFollowOnly ? 1 : 0,
        },
      },
    );
 
    return (response.data.backlinks ?? []).map((b: any) => ({
      sourceUrl:     b.source_url,
      targetUrl:     b.target_url,
      anchorText:    b.anchor_text,
      trustFlow:     b.trust_flow,
      citationFlow:  b.citation_flow,
      isNoFollow:    b.nofollow,
      firstSeen:     b.first_seen,
      lastSeen:      b.last_seen,
    }));
  }
 
  // ── Backlink Metrics (batch) ─────────────────────────────────────────────────
 
  async getBacklinksMetrics(domains: string[]): Promise<BacklinksMetricsRow[]> {
    // SE Ranking supports up to 100 domains per call
    const response = await axios.post(
      `${this.baseUrl}/research/backlinks/metrics/`,
      { domains },
      { headers: { ...this.headers(), 'Content-Type': 'application/json' } },
    );
    return response.data.map((row: any) => ({
      domain:           row.domain,
      trustFlow:        row.trust_flow,
      citationFlow:     row.citation_flow,
      referringDomains: row.referring_domains,
      totalBacklinks:   row.total_backlinks,
    }));
  }
 
  // ── Keyword Rankings ─────────────────────────────────────────────────────────
 
  async getKeywordRankings(options: {
    domain:    string;
    keywords:  string[];
    searchEngine: 'google' | 'bing' | 'yahoo';
    location?: string;   // e.g. "United States"
  }): Promise<KeywordRankingRow[]> {
    const response = await axios.post(
      `${this.baseUrl}/keywords/check/`,
      {
        domain:          options.domain,
        keywords:        options.keywords,
        search_engine:   options.searchEngine,
        location_name:   options.location ?? 'United States',
      },
      { headers: { ...this.headers(), 'Content-Type': 'application/json' } },
    );
    return response.data.map((row: any) => ({
      keyword:  row.keyword,
      position: row.position,   // null if not in top 100
      url:      row.url,
      volume:   row.volume,
    }));
  }
 
  async verify(): Promise<void> {
    // Fetch account/subscription info
    const response = await axios.get(`${this.baseUrl}/system/account/`, {
      headers: this.headers(),
    });
    if (!response.data.email) {
      throw new Error('SE Ranking verification failed — invalid API key');
    }
  }
}