Channel Providers — Developer Reference

SocialServiceBase          ← base class: ExecuteSafely, ParseResponse
  └── GoogleServiceBase    ← adds Google-specific Authorize / AuthorizeCallback / RefreshToken
        └── GmailService, GoogleAdsService, GoogleAnalyticsService, ...
  └── MicrosoftServiceBase ← adds Microsoft-specific OAuth flow
        └── BingWebMasterToolsService
  └── ZohoServiceBase      ← adds Zoho-specific OAuth flow (supports dynamic accountsServer)
        └── ZohoBooksService
  └── FacebookService      ← self-contained (no shared base beyond SocialServiceBase)
  └── InstagramService
  └── LinkedInService      ← extra ICacheManager dependency
  └── TwitterService       ← supports both OAuth 1.0a AND OAuth 2.0
  └── SpotifyService

1. Client calls Authorize(callbackUrl, state)
   → Returns: redirect URL (string)

2. User authenticates on the 3rd-party site and is redirected back with ?code=...

3. Client calls AuthorizeCallback(code, callbackUrl)
   → Returns: OAuthInfo  { accessToken, refreshToken, expiresIn, expireOn, ... }

4. When token expires, call RefreshTokenAsync(refreshToken)
   → Returns: OAuthInfo (new accessToken, new expireOn)

interface OAuthInfo {
  access_token: string;       // Bearer token
  token_type: string;         // Usually "Bearer"
  expires_in: number | null;  // Seconds until token expires
  expireOn: Date | null;      // Computed: Date.now() + expires_in seconds (UTC)
  refresh_token: string;      // Use this to refresh when expired
  scope: string;
  id_token: string;           // Present for OpenID Connect flows (Google)
  accessTokenSecret: string;  // Twitter OAuth 1.0a only
  userId: string;
  username: string;
}

interface ProviderDescription {
  baseUrl: string;
  authorityUrl: string;
  accessTokenEndpoint: string;
  requestTokenEndpoint: string;
  refreshTokenEndpoint: string;
  userAuthorizationEndpoint: string;
  version: string;
  scopes: string;
  type: string;
}

export abstract class SocialServiceBase {
  protected abstract getConsumerKey(): string;
  protected abstract getConsumerSecret(): string;
  protected abstract getProviderDescription(): ProviderDescription;
 
  protected async executeSafely<T>(operation: () => Promise<T>): Promise<T | null> {
    try {
      return await operation();
    } catch (err) {
      console.error('Operation failed:', (err as Error).message);
      return null;
    }
  }
 
  protected parseResponse<T>(response: Response, body: string): T {
    if (!body) {
      throw new Error(`Empty response from API`);
    }
    if (response.ok) {
      const parsed = JSON.parse(body) as T;
      if (parsed == null) throw new Error(`Failed to deserialize response: ${body}`);
      return parsed;
    }
    throw new ChannelApiError(
      `API call failed. Status: ${response.status}. Body: ${body}`,
      response.status
    );
  }
}

import fetch from 'node-fetch';
 
export class GoogleServiceBase extends SocialServiceBase {
  constructor(
    private readonly clientId: string,
    private readonly clientSecret: string,
    private readonly providerDescription: ProviderDescription
  ) {
    super();
  }
 
  protected getConsumerKey() { return this.clientId; }
  protected getConsumerSecret() { return this.clientSecret; }
  protected getProviderDescription() { return this.providerDescription; }
 
  // Step 1: Build the redirect URL
  authorize(callbackUrl: string, state: string): string {
    const p = this.getProviderDescription();
    return (
      `${p.userAuthorizationEndpoint}?response_type=code` +
      `&client_id=${this.clientId}` +
      `&redirect_uri=${callbackUrl}` +
      `&state=${state}` +
      `&scope=${encodeURIComponent(p.scopes)}` +
      `&access_type=offline` +
      `&include_granted_scopes=true` +
      `&prompt=consent`
    );
  }
 
  // Step 2: Exchange auth code for tokens
  async authorizeCallback(code: string, callbackUrl: string): Promise<OAuthInfo> {
    const p = this.getProviderDescription();
    const params = new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      client_id: this.clientId,
      client_secret: this.clientSecret,
      redirect_uri: callbackUrl,
    });
    const res = await fetch(p.accessTokenEndpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: params.toString(),
    });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`Google AuthorizeCallback failed: ${body}`, res.status);
    const data = JSON.parse(body) as { access_token: string; refresh_token: string; expires_in: number; scope: string };
    return {
      accessToken: data.access_token,
      refreshToken: data.refresh_token,
      expiresInSeconds: data.expires_in,
      expireOn: new Date(Date.now() + data.expires_in * 1000),
      scope: p.scopes,
    };
  }
 
  // Step 3: Refresh an expired token
  async refreshTokenAsync(refreshToken: string): Promise<OAuthInfo> {
    const p = this.getProviderDescription();
    const params = new URLSearchParams({
      client_id: this.clientId,
      client_secret: this.clientSecret,
      refresh_token: refreshToken,
      grant_type: 'refresh_token',
    });
    const res = await fetch(p.refreshTokenEndpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: params.toString(),
    });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`Google RefreshToken failed: ${body}`, res.status);
    const data = JSON.parse(body) as { access_token: string; expires_in: number; scope: string };
    return {
      accessToken: data.access_token,
      refreshToken,                // Google does not re-issue the refresh token
      expiresInSeconds: data.expires_in,
      expireOn: new Date(Date.now() + data.expires_in * 1000),
      scope: data.scope,
    };
  }
}

interface IGoogleChannelService {
  authorize(callbackUrl: string, state: string): string;
  authorizeCallback(code: string, callbackUrl: string): Promise<OAuthInfo>;
  refreshTokenAsync(refreshToken: string): Promise<OAuthInfo>;
}

{userAuthorizationEndpoint}
  ?response_type=code
  &client_id={clientId}
  &redirect_uri={callbackUrl}
  &state={state}
  &scope={scopes}
  &access_type=offline
  &include_granted_scopes=true
  &prompt=consent

https://www.googleapis.com/auth/gmail.send

const GMAIL_PROVIDER: ProviderDescription = {
  baseUrl: 'https://gmail.googleapis.com',
  authorityUrl: '',
  requestTokenEndpoint: '',
  userAuthorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
  accessTokenEndpoint: 'https://oauth2.googleapis.com/token',
  refreshTokenEndpoint: 'https://www.googleapis.com/oauth2/v4/token',
  version: '1.0',
  scopes: 'https://www.googleapis.com/auth/gmail.send',
  type: 'Gmail',
};
 
export class GmailService extends GoogleServiceBase {
  constructor() {
    super(
      process.env.GMAIL_APP_ID!,
      process.env.GMAIL_APP_SECRET!,
      GMAIL_PROVIDER
    );
  }
  // authorize(), authorizeCallback(), refreshTokenAsync() are all inherited from GoogleServiceBase
}
 
// Usage:
const gmail = new GmailService();
 
// Step 1 - redirect user to this URL
const redirectUrl = gmail.authorize('https://yourdomain.com/callback', 'random-state-value');
 
// Step 2 - after redirect, exchange code for tokens
const tokens = await gmail.authorizeCallback(req.query.code, 'https://yourdomain.com/callback');
// tokens.accessToken, tokens.refreshToken, tokens.expireOn
 
// Step 3 - refresh when expired
const refreshed = await gmail.refreshTokenAsync(tokens.refreshToken);

https://www.googleapis.com/auth/adwords

interface GoogleAdsKeywordMetricsInputDTO {
  keyword: string;
  startDate: Date;
  endDate: Date;
}
 
interface GoogleAdsKeywordMetricsResponseDTO {
  keyword: string;
  clicks: number;
  impressions: number;
  ctr: number;
  topImpressionPercentage: number;
}

const GOOGLE_ADS_PROVIDER: ProviderDescription = {
  baseUrl: 'https://googleads.googleapis.com/v20',
  authorityUrl: '',
  requestTokenEndpoint: '',
  userAuthorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
  accessTokenEndpoint: 'https://oauth2.googleapis.com/token',
  refreshTokenEndpoint: 'https://www.googleapis.com/oauth2/v4/token',
  version: '1.0',
  scopes: 'https://www.googleapis.com/auth/adwords',
  type: 'Google Ads',
};
 
export class GoogleAdsService extends GoogleServiceBase {
  private readonly developerToken: string;
 
  constructor() {
    super(
      process.env.GOOGLE_ADS_APP_ID!,
      process.env.GOOGLE_ADS_APP_SECRET!,
      GOOGLE_ADS_PROVIDER
    );
    this.developerToken = process.env.GOOGLE_ADS_DEVELOPER_TOKEN!;
  }
 
  private adsHeaders(token: string, parentId?: string): Record<string, string> {
    const headers: Record<string, string> = {
      Authorization: `Bearer ${token}`,
      'developer-token': this.developerToken,
    };
    if (parentId) headers['login-customer-id'] = parentId;
    return headers;
  }
 
  private async adsQuery<T>(customerId: string, token: string, query: string, parentId?: string, nextPageToken?: string): Promise<T> {
    const url = `${this.getProviderDescription().baseUrl}/customers/${customerId}/googleAds:search`;
    const body = JSON.stringify({ query, ...(nextPageToken ? { pageToken: nextPageToken } : {}) });
    const res = await fetch(url, {
      method: 'POST',
      headers: { ...this.adsHeaders(token, parentId), 'Content-Type': 'application/json' },
      body,
    });
    const text = await res.text();
    if (!res.ok) throw new ChannelApiError(`Google Ads query failed: ${text}`, res.status);
    return JSON.parse(text) as T;
  }
 
  async getAllCustomers(token: string): Promise<GoogleAdsCustomer[]> {
    const url = `${this.getProviderDescription().baseUrl}/customers:listAccessibleCustomers`;
    const res = await fetch(url, { headers: this.adsHeaders(token) });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`getAllCustomers failed: ${body}`, res.status);
    const json = JSON.parse(body) as { resourceNames?: string[] };
    const customers: GoogleAdsCustomer[] = [];
    for (const resourceName of json.resourceNames ?? []) {
      const cId = resourceName.split('/')[1];
      try {
        const list = await this.getCustomerHierarchyDetails(cId, token);
        if (list) customers.push(...list);
      } catch { continue; }
    }
    return customers.sort((a, b) => a.descriptiveName.localeCompare(b.descriptiveName));
  }
 
  async getCustomerHierarchyDetails(customerId: string, token: string): Promise<GoogleAdsCustomer[]> {
    const query = `SELECT customer_client.client_customer, customer_client.level, customer_client.manager,
      customer_client.descriptive_name, customer_client.currency_code, customer_client.time_zone,
      customer_client.id FROM customer_client`;
    const result = await this.adsQuery<{ results?: { customerClient: GoogleAdsCustomer }[] }>(customerId, token, query);
    return (result.results ?? []).map(r => r.customerClient);
  }
 
  async getCustomerDetails(customerId: string, parentId: string, token: string): Promise<GoogleAdsCustomer> {
    const query = `SELECT customer.id, customer.resource_name, customer.descriptive_name,
      customer.manager, customer.test_account, customer.currency_code FROM customer`;
    const result = await this.adsQuery<{ results?: { customer: GoogleAdsCustomer }[] }>(customerId, token, query, parentId);
    return result.results?.[0]?.customer ?? null;
  }
 
  async getCampaignsAsLookUp(customerId: string, parentId: string, token: string): Promise<GoogleAdsCampaignsLookUpItem[]> {
    const query = `SELECT campaign.name, campaign.id FROM campaign`;
    const result = await this.adsQuery<{ results?: GoogleAdsCampaignsLookUpItem[] }>(customerId, token, query, parentId);
    return result.results ?? [];
  }
 
  async getGoogleAdsSearchTerms(
    customerId: string, parentId: string, campaignId: string,
    token: string, nextPageToken: string, _pageNumber: number
  ): Promise<GoogleAdsSearchTermsModel> {
    const query = `SELECT search_term_view.search_term, search_term_view.resource_name,
      search_term_view.status, segments.keyword.info.text, segments.search_term_match_type,
      ad_group.id, ad_group.name, metrics.clicks, metrics.average_cpc, metrics.ctr,
      metrics.impressions, metrics.conversions, metrics.cost_micros, campaign.id, campaign.name
      FROM search_term_view
      WHERE segments.date DURING YESTERDAY AND campaign.id = '${campaignId}'`;
    return this.adsQuery<GoogleAdsSearchTermsModel>(customerId, token, query, parentId, nextPageToken);
  }
 
  async getGoogleAdsSearchTermsByDate(
    customerId: string, parentId: string, campaignId: string, campaignDate: Date,
    token: string, nextPageToken: string, _pageNumber: number
  ): Promise<GoogleAdsSearchTermsModel> {
    const dateStr = campaignDate.toISOString().split('T')[0];
    const query = `SELECT search_term_view.search_term, search_term_view.resource_name,
      search_term_view.status, segments.keyword.info.text, segments.search_term_match_type,
      ad_group.id, ad_group.name, metrics.clicks, metrics.average_cpc, metrics.ctr,
      metrics.impressions, metrics.conversions, metrics.cost_micros, campaign.id, campaign.name
      FROM search_term_view
      WHERE segments.date = '${dateStr}' AND campaign.id = '${campaignId}'`;
    return this.adsQuery<GoogleAdsSearchTermsModel>(customerId, token, query, parentId, nextPageToken);
  }
 
  async getGoogleAdsPositiveKeywords(
    customerId: string, parentId: string, campaignId: string,
    token: string, nextPageToken: string, _pageNumber: number
  ): Promise<GoogleAdsPositiveKeywordsModel> {
    const query = `SELECT campaign.id, campaign.name, ad_group.id, ad_group.name,
      ad_group_criterion.criterion_id, ad_group_criterion.status,
      ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type,
      ad_group_criterion.quality_info.quality_score
      FROM ad_group_criterion
      WHERE ad_group_criterion.type = KEYWORD AND ad_group_criterion.status != REMOVED
        AND campaign.id = '${campaignId}'`;
    return this.adsQuery<GoogleAdsPositiveKeywordsModel>(customerId, token, query, parentId, nextPageToken);
  }
 
  async getGoogleAdsCampaignLevelNegativeKeywords(
    customerId: string, parentId: string, campaignId: string,
    token: string, nextPageToken: string, _pageNumber: number
  ): Promise<GoogleAdsCampaignNegativeKeywordsModel> {
    const query = `SELECT campaign.id, campaign.name,
      campaign_criterion.criterion_id, campaign_criterion.status,
      campaign_criterion.keyword.text, campaign_criterion.keyword.match_type
      FROM campaign_criterion
      WHERE campaign_criterion.type = KEYWORD AND campaign_criterion.negative = true
        AND campaign.id = '${campaignId}'`;
    return this.adsQuery<GoogleAdsCampaignNegativeKeywordsModel>(customerId, token, query, parentId, nextPageToken);
  }
 
  async getMonthlyKeywordMetrics(
    customerId: string, parentId: string, keywords: string[], token: string
  ): Promise<GoogleAdsKeywordsMetricsModel> {
    const url = `${this.getProviderDescription().baseUrl}/customers/${customerId}:generateKeywordHistoricalMetrics`;
    const now = new Date();
    const lastMonth = new Date(now.getFullYear(), now.getMonth() - 1, 1);
    const body = JSON.stringify({
      keywords,
      historicalMetricsOptions: { yearMonthRange: {
        start: { year: lastMonth.getFullYear(), month: lastMonth.getMonth() + 1 },
        end: { year: now.getFullYear(), month: now.getMonth() + 1 },
      }},
      includeAverageMonthlySearches: true,
    });
    const res = await fetch(url, {
      method: 'POST',
      headers: { ...this.adsHeaders(token, parentId), 'Content-Type': 'application/json' },
      body,
    });
    const text = await res.text();
    if (!res.ok) throw new ChannelApiError(`getMonthlyKeywordMetrics failed: ${text}`, res.status);
    return JSON.parse(text) as GoogleAdsKeywordsMetricsModel;
  }
}
 
// Usage:
const googleAds = new GoogleAdsService();
const redirectUrl = googleAds.authorize('https://yourdomain.com/callback', 'state-xyz');
const tokens = await googleAds.authorizeCallback(code, 'https://yourdomain.com/callback');
const customers = await googleAds.getAllCustomers(tokens.accessToken);
const campaigns = await googleAds.getCampaignsAsLookUp(customers[0].id, customers[0].managerId, tokens.accessToken);
const searchTerms = await googleAds.getGoogleAdsSearchTerms(customers[0].id, customers[0].managerId, campaigns[0].id, tokens.accessToken, null, 1);

https://www.googleapis.com/auth/analytics.readonly

const ORGANIC_CHANNELS = ['Organic Search', 'Organic Shopping', 'Organic Social', 'Organic Video'];
const GA_DATA_API = 'https://analyticsdata.googleapis.com/v1beta';
const GA_ADMIN_API = 'https://analyticsadmin.googleapis.com/v1beta';
 
const GOOGLE_ANALYTICS_PROVIDER: ProviderDescription = {
  baseUrl: GA_ADMIN_API + '/',
  authorityUrl: '',
  requestTokenEndpoint: '',
  userAuthorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
  accessTokenEndpoint: 'https://oauth2.googleapis.com/token',
  refreshTokenEndpoint: 'https://www.googleapis.com/oauth2/v4/token',
  version: '1.0',
  scopes: 'https://www.googleapis.com/auth/analytics.readonly',
  type: 'Google Analytics',
};
 
export class GoogleAnalyticsService extends GoogleServiceBase {
  constructor() {
    super(
      process.env.GOOGLE_ANALYTICS_APP_ID!,
      process.env.GOOGLE_ANALYTICS_APP_SECRET!,
      GOOGLE_ANALYTICS_PROVIDER
    );
  }
 
  private fmt(d: Date): string {
    return d.toISOString().split('T')[0]; // 'yyyy-MM-dd'
  }
 
  private parseDate(s: string): Date {
    // GA returns dates as 'yyyyMMdd'
    return new Date(`${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6, 8)}`);
  }
 
  private async runReport(propertyId: string, token: string, body: object): Promise<any> {
    const res = await fetch(`${GA_DATA_API}/properties/${propertyId}:runReport`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
    const text = await res.text();
    if (!res.ok) throw new ChannelApiError(`GA runReport failed: ${text}`, res.status);
    return JSON.parse(text);
  }
 
  async getAllAccounts(token: string): Promise<GoogleAnalyticsAccount[]> {
    const res = await fetch(`${GA_ADMIN_API}/accountSummaries`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`getAllAccounts failed: ${body}`, res.status);
    const data = JSON.parse(body) as { accountSummaries?: GoogleAnalyticsAccount[] };
    return data.accountSummaries ?? [];
  }
 
  async getOrganicTrafficMetrics(propertyId: string, token: string, startDate: Date, endDate: Date): Promise<GAOrganicTrafficMetrics> {
    const result = await this.runReport(propertyId, token, {
      dateRanges: [{ startDate: this.fmt(startDate), endDate: this.fmt(endDate) }],
      dimensions: [{ name: 'sessionDefaultChannelGroup' }],
      metrics: [{ name: 'activeUsers' }, { name: 'newUsers' }, { name: 'userEngagementDuration' }],
      dimensionFilter: { filter: { fieldName: 'sessionDefaultChannelGroup', inListFilter: { values: ORGANIC_CHANNELS } } },
    });
    const totals = result.totals?.[0]?.metricValues ?? [];
    return {
      channel: 'Organic',
      activeUsers: parseInt(totals[0]?.value ?? '0'),
      newUsers: parseInt(totals[1]?.value ?? '0'),
      totalEngagementTimeSeconds: parseFloat(totals[2]?.value ?? '0'),
    };
  }
 
  async getDailyOrganicTrafficMetrics(propertyId: string, token: string, startDate: Date, endDate: Date): Promise<GADailyOrganicTrafficMetrics[]> {
    const result = await this.runReport(propertyId, token, {
      dateRanges: [{ startDate: this.fmt(startDate), endDate: this.fmt(endDate) }],
      dimensions: [{ name: 'date' }],
      metrics: [{ name: 'activeUsers' }, { name: 'newUsers' }, { name: 'userEngagementDuration' }],
      dimensionFilter: { filter: { fieldName: 'sessionDefaultChannelGroup', inListFilter: { values: ORGANIC_CHANNELS } } },
    });
    return (result.rows ?? [])
      .map((row: any) => ({
        date: this.parseDate(row.dimensionValues[0].value),
        channel: 'Organic',
        activeUsers: parseInt(row.metricValues[0].value ?? '0'),
        newUsers: parseInt(row.metricValues[1].value ?? '0'),
        totalEngagementTimeSeconds: parseFloat(row.metricValues[2].value ?? '0'),
      }))
      .sort((a: any, b: any) => a.date - b.date);
  }
 
  async getSessionsByChannelGroupsOverTime(
    propertyId: string, token: string, startDate: Date, endDate: Date, organicOnly = false
  ): Promise<GAChannelSessionsOverTime[]> {
    const body: any = {
      dateRanges: [{ startDate: this.fmt(startDate), endDate: this.fmt(endDate) }],
      dimensions: [{ name: 'date' }, { name: 'sessionDefaultChannelGroup' }],
      metrics: [{ name: 'sessions' }],
      orderBys: [{ dimension: { dimensionName: 'date' }, desc: false }],
    };
    if (organicOnly) {
      body.dimensionFilter = { filter: { fieldName: 'sessionDefaultChannelGroup', inListFilter: { values: ORGANIC_CHANNELS } } };
    }
    const result = await this.runReport(propertyId, token, body);
    return (result.rows ?? []).map((row: any) => ({
      date: this.parseDate(row.dimensionValues[0].value),
      channelGroup: row.dimensionValues[1].value ?? 'Unassigned',
      sessions: parseInt(row.metricValues[0].value ?? '0'),
    })).sort((a: any, b: any) => a.date - b.date);
  }
 
  async getTrafficAcquisitionWithEventsAsync(
    propertyId: string, token: string, startDate: Date, endDate: Date,
    channels?: string[], organicOnly = false
  ): Promise<GAChannelEventAndEngagementResult> {
    const body: any = {
      dateRanges: [{ startDate: this.fmt(startDate), endDate: this.fmt(endDate) }],
      dimensions: [{ name: 'sessionDefaultChannelGroup' }],
      metrics: [
        { name: 'sessions' }, { name: 'engagedSessions' }, { name: 'engagementRate' },
        { name: 'userEngagementDuration' }, { name: 'eventCount' }, { name: 'eventsPerSession' },
        { name: 'keyEvents' }, { name: 'sessionKeyEventRate' },
      ],
    };
    const filterValues = organicOnly ? ORGANIC_CHANNELS : (channels ?? []);
    if (filterValues.length > 0) {
      body.dimensionFilter = { filter: { fieldName: 'sessionDefaultChannelGroup', inListFilter: { values: filterValues } } };
    }
    const result = await this.runReport(propertyId, token, body);
    const items = (result.rows ?? []).map((row: any) => {
      const m = row.metricValues;
      return {
        channelGroup: row.dimensionValues[0].value ?? 'Unassigned',
        sessions: parseInt(m[0].value), engagedSessions: parseInt(m[1].value),
        engagementRate: Math.round(parseFloat(m[2].value) * 100 * 100) / 100,
        totalEngagementTimeSeconds: Math.round(parseFloat(m[3].value) * 100) / 100,
        eventCount: parseInt(m[4].value),
        eventsPerSession: Math.round(parseFloat(m[5].value) * 100) / 100,
        keyEvents: parseInt(m[6].value),
        sessionKeyEventRate: Math.round(parseFloat(m[7].value) * 100 * 100) / 100,
      };
    });
    return { metricsElements: items };
  }
 
  async getLandingPageTrafficAsync(
    propertyId: string, token: string, startDate: Date, endDate: Date,
    organicOnly = false, query?: string
  ): Promise<GALandingPagesTrafficResult> {
    const body: any = {
      dateRanges: [{ startDate: this.fmt(startDate), endDate: this.fmt(endDate) }],
      dimensions: [{ name: 'landingPage' }],
      metrics: [
        { name: 'sessions' }, { name: 'activeUsers' }, { name: 'newUsers' },
        { name: 'userEngagementDuration' }, { name: 'keyEvents' }, { name: 'sessionKeyEventRate' },
      ],
    };
    const filters: any[] = [];
    if (organicOnly) filters.push({ fieldName: 'sessionDefaultChannelGroup', inListFilter: { values: ORGANIC_CHANNELS } });
    if (query) filters.push({ fieldName: 'landingPage', stringFilter: { matchType: 'CONTAINS', value: query, caseSensitive: false } });
    if (filters.length === 1) body.dimensionFilter = { filter: filters[0] };
    else if (filters.length > 1) body.dimensionFilter = { andGroup: { expressions: filters.map(f => ({ filter: f })) } };
    const result = await this.runReport(propertyId, token, body);
    const items = (result.rows ?? []).map((row: any) => {
      const m = row.metricValues;
      return {
        landingPage: row.dimensionValues[0].value ?? '(not set)',
        sessions: parseInt(m[0].value), activeUsers: parseInt(m[1].value),
        newUsers: parseInt(m[2].value),
        totalEngagementTimeSeconds: parseFloat(m[3].value),
        keyEvents: parseInt(m[4].value),
        sessionKeyEventRate: Math.round(parseFloat(m[5].value) * 100 * 100) / 100,
      };
    });
    return { items };
  }
}
 
// Usage:
const ga = new GoogleAnalyticsService();
const redirectUrl = ga.authorize('https://yourdomain.com/callback', 'state-xyz');
const tokens = await ga.authorizeCallback(code, 'https://yourdomain.com/callback');
const accounts = await ga.getAllAccounts(tokens.accessToken);
const organic = await ga.getOrganicTrafficMetrics('properties/123456', tokens.accessToken, new Date('2026-01-01'), new Date('2026-03-31'));
const daily = await ga.getDailyOrganicTrafficMetrics('properties/123456', tokens.accessToken, new Date('2026-01-01'), new Date('2026-03-31'));

https://www.googleapis.com/auth/business.manage

interface GBPPostRequestModel {
  summary: string;
  callToAction?: GBPCallToAction;
  event?: GBPEvent;
  offer?: GBPOffer;
  media?: GBPPostMedia[];
}

const GBP_ACCOUNT_MGMT_API = 'https://mybusinessaccountmanagement.googleapis.com/v1';
const GBP_BUSINESS_INFO_API = 'https://mybusinessbusinessinformation.googleapis.com/v1';
const GBP_PERFORMANCE_API = 'https://businessprofileperformance.googleapis.com/v1';
 
const GOOGLE_BUSINESS_PROFILE_PROVIDER: ProviderDescription = {
  baseUrl: 'https://mybusiness.googleapis.com/v4/',
  authorityUrl: '',
  requestTokenEndpoint: '',
  userAuthorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
  accessTokenEndpoint: 'https://oauth2.googleapis.com/token',
  refreshTokenEndpoint: 'https://www.googleapis.com/oauth2/v4/token',
  version: '1.0',
  scopes: 'https://www.googleapis.com/auth/business.manage',
  type: 'Google Business Profile',
};
 
export class GoogleBusinessProfileService extends GoogleServiceBase {
  constructor() {
    super(
      process.env.GOOGLE_MY_BUSINESS_APP_ID!,
      process.env.GOOGLE_MY_BUSINESS_APP_SECRET!,
      GOOGLE_BUSINESS_PROFILE_PROVIDER
    );
  }
 
  async getAllLocations(token: string): Promise<GBPLocation[]> {
    const res = await fetch(`${GBP_ACCOUNT_MGMT_API}/accounts`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`GBP getAllLocations accounts failed: ${body}`, res.status);
    const accounts = JSON.parse(body) as { accounts?: { name: string }[] };
    const all: GBPLocation[] = [];
    for (const account of accounts.accounts ?? []) {
      const accountId = account.name.split('/')[1];
      const locs = await this.getAllLocationsForAccount(accountId, token);
      all.push(...locs);
    }
    return all.sort((a, b) => a.name.localeCompare(b.name));
  }
 
  async getAllLocationsForAccount(accountId: string, token: string): Promise<GBPLocation[]> {
    const locations: GBPLocation[] = [];
    let pageToken: string | undefined;
    do {
      let url = `${GBP_BUSINESS_INFO_API}/accounts/${accountId}/locations` +
        `?read_mask=name,title,metadata.place_id,categories,phone_numbers.primary_phone,storefront_address.region_code&pageSize=100`;
      if (pageToken) url += `&pageToken=${encodeURIComponent(pageToken)}`;
      const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
      const body = await res.text();
      if (!res.ok) throw new ChannelApiError(`GBP getAllLocationsForAccount failed: ${body}`, res.status);
      const data = JSON.parse(body) as { locations?: GBPLocation[]; nextPageToken?: string };
      for (const loc of data.locations ?? []) {
        loc.accountId = accountId;
        locations.push(loc);
      }
      pageToken = data.nextPageToken;
    } while (pageToken);
    return locations;
  }
 
  async getMultiDailyMetrics(locationId: string, startDate: Date, endDate: Date, token: string): Promise<GBPMultiDailyMetricsResponse> {
    const metrics = [
      'WEBSITE_CLICKS', 'CALL_CLICKS', 'BUSINESS_IMPRESSIONS_DESKTOP_MAPS',
      'BUSINESS_IMPRESSIONS_DESKTOP_SEARCH', 'BUSINESS_IMPRESSIONS_MOBILE_MAPS',
      'BUSINESS_IMPRESSIONS_MOBILE_SEARCH', 'BUSINESS_CONVERSATIONS',
      'BUSINESS_DIRECTION_REQUESTS', 'BUSINESS_BOOKINGS', 'BUSINESS_FOOD_ORDERS',
      'BUSINESS_FOOD_MENU_CLICKS',
    ].map(m => `dailyMetrics=${m}`).join('&');
    const url = `${GBP_PERFORMANCE_API}/locations/${locationId}:fetchMultiDailyMetricsTimeSeries?${metrics}` +
      `&dailyRange.start_date.year=${startDate.getFullYear()}&dailyRange.start_date.month=${startDate.getMonth() + 1}&dailyRange.start_date.day=${startDate.getDate()}` +
      `&dailyRange.end_date.year=${endDate.getFullYear()}&dailyRange.end_date.month=${endDate.getMonth() + 1}&dailyRange.end_date.day=${endDate.getDate()}`;
    const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`GBP getMultiDailyMetrics failed: ${body}`, res.status);
    return JSON.parse(body) as GBPMultiDailyMetricsResponse;
  }
 
  async getSearchKeywordsImpressions(locationId: string, startDate: Date, endDate: Date, token: string): Promise<GBPSearchKeywordImpression[]> {
    const results: GBPSearchKeywordImpression[] = [];
    let nextPageToken: string | undefined;
    do {
      let url = `${GBP_PERFORMANCE_API}/locations/${locationId}/searchkeywords/impressions/monthly` +
        `?monthlyRange.start_month.year=${startDate.getFullYear()}&monthlyRange.start_month.month=${startDate.getMonth() + 1}` +
        `&monthlyRange.end_month.year=${endDate.getFullYear()}&monthlyRange.end_month.month=${endDate.getMonth() + 1}`;
      if (nextPageToken) url += `&pageToken=${encodeURIComponent(nextPageToken)}`;
      const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
      const body = await res.text();
      if (!res.ok) throw new ChannelApiError(`GBP getSearchKeywords failed: ${body}`, res.status);
      const data = JSON.parse(body) as { searchKeywordsCounts?: GBPSearchKeywordImpression[]; nextPageToken?: string };
      results.push(...(data.searchKeywordsCounts ?? []));
      nextPageToken = data.nextPageToken;
    } while (nextPageToken);
    return results;
  }
 
  async createPostAsync(accountId: string, locationId: string, token: string, model: GBPPostRequestModel): Promise<GBPPostResponse> {
    const medias = model.imageUrls?.filter(Boolean).map(url => ({ mediaFormat: 'PHOTO', sourceUrl: url }));
    const postBody: any = { summary: model.content, callToAction: model.callToAction, media: medias };
    if (model.event) postBody.event = model.event;
    if (model.offer) postBody.offer = model.offer;
    const res = await fetch(`${this.getProviderDescription().baseUrl}accounts/${accountId}/locations/${locationId}/localPosts`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(postBody),
    });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`GBP createPost failed: ${body}`, res.status);
    return JSON.parse(body) as GBPPostResponse;
  }
 
  async getAllReviews(locationId: string, accountId: string, token: string, pages = 1): Promise<GBPReviewsResponse> {
    const res = await fetch(`${this.getProviderDescription().baseUrl}accounts/${accountId}/locations/${locationId}/reviews?pageSize=50`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`GBP getAllReviews failed: ${body}`, res.status);
    return JSON.parse(body) as GBPReviewsResponse;
  }
 
  async postReviewReplyAsync(locationId: string, accountId: string, reviewId: string, replyText: string, token: string): Promise<boolean> {
    const res = await fetch(`${this.getProviderDescription().baseUrl}accounts/${accountId}/locations/${locationId}/reviews/${reviewId}/reply`, {
      method: 'PUT',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ comment: replyText }),
    });
    return res.ok;
  }
}
 
// Usage:
const gbp = new GoogleBusinessProfileService();
const tokens = await gbp.authorizeCallback(code, callbackUrl);
const locations = await gbp.getAllLocations(tokens.accessToken);
const metrics = await gbp.getMultiDailyMetrics(locations[0].name.split('/')[1], new Date('2026-01-01'), new Date('2026-03-31'), tokens.accessToken);

https://www.googleapis.com/auth/webmasters

interface GSCMetricsInputDTO {
  startDate: Date | null;
  endDate: Date | null;
}
 
interface GSCSearchFilterInputDTO {
  startDate: Date;
  endDate: Date;
  query?: string;
  page?: number;      // default 1
  size?: number;      // default 100
  sort?: string;      // default "impressions"
  order?: string;     // default "descending"
}
 
interface PageMetricsInputDTO {
  url: string;
  startDate: Date;
  endDate: Date;
}

const GSC_PROVIDER: ProviderDescription = {
  baseUrl: 'https://www.googleapis.com/webmasters/v3',
  authorityUrl: '',
  requestTokenEndpoint: '',
  userAuthorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
  accessTokenEndpoint: 'https://oauth2.googleapis.com/token',
  refreshTokenEndpoint: 'https://www.googleapis.com/oauth2/v4/token',
  version: '1.0',
  scopes: 'https://www.googleapis.com/auth/webmasters',
  type: 'Google Search Console',
};
 
export class GoogleSearchConsoleService extends GoogleServiceBase {
  constructor() {
    super(
      process.env.GOOGLE_SEARCH_CONSOLE_APP_ID!,
      process.env.GOOGLE_SEARCH_CONSOLE_APP_SECRET!,
      GSC_PROVIDER
    );
  }
 
  private encodeSite(site: string): string {
    return site.startsWith('http') ? encodeURIComponent(site) : site;
  }
 
  private fmt(d: Date): string { return d.toISOString().split('T')[0]; }
 
  private async searchAnalytics(site: string, token: string, body: object): Promise<any> {
    const siteId = this.encodeSite(site);
    const res = await fetch(`${this.getProviderDescription().baseUrl}/sites/${siteId}/searchAnalytics/query`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
    const text = await res.text();
    if (!res.ok) throw new ChannelApiError(`GSC searchAnalytics failed: ${text}`, res.status);
    return JSON.parse(text);
  }
 
  async getAllSites(token: string): Promise<GoogleSiteModel[]> {
    const res = await fetch(`${this.getProviderDescription().baseUrl}/sites`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`GSC getAllSites failed: ${body}`, res.status);
    const data = JSON.parse(body) as { siteEntry?: GoogleSiteModel[] };
    return data.siteEntry ?? [];
  }
 
  async getStats(site: string, token: string, input: GSCMetricsInputDTO, size = 1000): Promise<GSCMetricsResponseDTO> {
    const body: any = { dimensions: ['date'], rowLimit: size };
    if (input.startDate) body.startDate = this.fmt(input.startDate);
    if (input.endDate) body.endDate = this.fmt(input.endDate);
    const result = await this.searchAnalytics(site, token, body);
    const data = (result.rows ?? []).map((r: any) => ({
      date: r.keys[0], clicks: r.clicks, impressions: r.impressions,
      ctr: Math.round(r.ctr * 100) / 100, position: Math.round(r.position * 100) / 100,
    }));
    return { data };
  }
 
  async getPageMetrics(site: string, token: string, input: PageMetricsInputDTO): Promise<PageMetricsResponseDTO> {
    const body = {
      startDate: this.fmt(input.startDate), endDate: this.fmt(input.endDate),
      dimensions: ['page'], rowLimit: 100,
      dimensionFilterGroups: [{ filters: [{ dimension: 'page', expression: input.url }] }],
    };
    const result = await this.searchAnalytics(site, token, body);
    const row = result.rows?.[0];
    if (!row) throw new Error(`No data for ${input.url}`);
    return { url: row.keys[0], clicks: row.clicks, impressions: row.impressions, ctr: row.ctr, position: row.position };
  }
 
  async getKeywordStats(site: string, token: string, startDate: Date, endDate: Date): Promise<SearchQueryStatsModel[]> {
    const body = {
      startDate: this.fmt(startDate), endDate: this.fmt(endDate),
      dimensions: ['query'], rowLimit: 10000,
    };
    const result = await this.searchAnalytics(site, token, body);
    return result.rows ?? [];
  }
 
  async getStatsByKeyword(site: string, token: string, input: GSCKeywordMetricsInputDTO, size: number): Promise<GSCKeywordMetricsResponseDTO> {
    const body: any = {
      dimensions: ['date'], rowLimit: size,
      dimensionFilterGroups: [{ filters: [{ dimension: 'query', expression: input.keyword }] }],
    };
    if (input.startDate) body.startDate = this.fmt(input.startDate);
    if (input.endDate) body.endDate = this.fmt(input.endDate);
    const result = await this.searchAnalytics(site, token, body);
    const data = (result.rows ?? []).map((r: any) => ({
      date: r.keys[0], clicks: r.clicks, impressions: r.impressions,
      ctr: Math.round(r.ctr * 100) / 100, position: Math.round(r.position * 100) / 100,
    }));
    return { keyword: input.keyword, data };
  }
 
  async searchQueries(site: string, token: string, input: GSCSearchFilterInputDTO): Promise<GSCKeywordMetricsDTO[]> {
    const body: any = {
      startDate: this.fmt(input.startDate), endDate: this.fmt(input.endDate),
      dimensions: ['query'], rowLimit: input.size ?? 100,
      startRow: ((input.page ?? 1) - 1) * (input.size ?? 100),
    };
    if (input.query) body.dimensionFilterGroups = [{ filters: [{ dimension: 'query', expression: input.query }] }];
    const result = await this.searchAnalytics(site, token, body);
    return (result.rows ?? []).map((r: any) => ({
      keyword: r.keys[0], clicks: r.clicks, impressions: r.impressions, ctr: r.ctr, position: r.position,
    }));
  }
}
 
// Usage:
const gsc = new GoogleSearchConsoleService();
const tokens = await gsc.authorizeCallback(code, callbackUrl);
const sites = await gsc.getAllSites(tokens.accessToken);
const stats = await gsc.getStats(sites[0].siteUrl, tokens.accessToken, { startDate: new Date('2026-01-01'), endDate: new Date('2026-03-31') });
const kwStats = await gsc.getKeywordStats(sites[0].siteUrl, tokens.accessToken, new Date('2026-01-01'), new Date('2026-03-31'));

public_profile, pages_show_list, pages_read_engagement, pages_manage_posts, publish_video

interface NewSocialPostRequestModel {
  message: string;
  mediaUrls?: string[];
  mediaType?: string;   // "image" | "video"
}
interface NewSocialPostResponseModel {
  id: string;
}

const FB_BASE = 'https://graph.facebook.com';
const FB_SCOPES = 'public_profile,pages_show_list,pages_read_engagement,pages_manage_posts,publish_video';
 
export class FacebookService {
  private readonly appId: string;
  private readonly appSecret: string;
 
  constructor() {
    this.appId = process.env.FACEBOOK_APP_ID!;
    this.appSecret = process.env.FACEBOOK_APP_SECRET!;
  }
 
  // Step 1
  authorize(callbackUrl: string, state: string): string {
    return `https://www.facebook.com/dialog/oauth?client_id=${this.appId}&redirect_uri=${callbackUrl}&scope=${FB_SCOPES}&state=${state}`;
  }
 
  // Step 2 — returns a short-lived user token (~1 hour)
  async authorizeCallback(code: string, callbackUrl: string): Promise<OAuthInfo> {
    const res = await fetch(`${FB_BASE}/oauth/access_token?client_id=${this.appId}&client_secret=${this.appSecret}&code=${code}&redirect_uri=${callbackUrl}`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB authorizeCallback failed: ${body}`, res.status);
    const data = JSON.parse(body);
    return {
      accessToken: data.access_token,
      tokenType: data.token_type,
      expiresInSeconds: data.expires_in,
      expireOn: data.expires_in ? new Date(Date.now() + data.expires_in * 1000) : null,
    };
  }
 
  // Exchange short-lived user token for a 60-day token
  async getLongLivedToken(shortToken: string): Promise<OAuthInfo> {
    const res = await fetch(`${FB_BASE}/oauth/access_token?grant_type=fb_exchange_token&client_id=${this.appId}&client_secret=${this.appSecret}&fb_exchange_token=${shortToken}`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB getLongLivedToken failed: ${body}`, res.status);
    const data = JSON.parse(body);
    return {
      accessToken: data.access_token,
      expiresInSeconds: data.expires_in,
      expireOn: data.expires_in ? new Date(Date.now() + data.expires_in * 1000) : null,
    };
  }
 
  async getAppToken(): Promise<string> {
    const res = await fetch(`${FB_BASE}/oauth/access_token?client_id=${this.appId}&client_secret=${this.appSecret}&grant_type=client_credentials`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB getAppToken failed: ${body}`, res.status);
    return JSON.parse(body).access_token;
  }
 
  async debugToken(token: string, appToken: string): Promise<FacebookToken> {
    const res = await fetch(`${FB_BASE}/debug_token?input_token=${token}&access_token=${appToken}`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB debugToken failed: ${body}`, res.status);
    return JSON.parse(body);
  }
 
  async getFacebookPages(token: string): Promise<FacebookSearchResult<FacebookPageInfo>> {
    const res = await fetch(`${FB_BASE}/me/accounts?access_token=${token}`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB getFacebookPages failed: ${body}`, res.status);
    return JSON.parse(body);
  }
 
  async getPageToken(pageId: string, token: string): Promise<FacebookPageToken> {
    const res = await fetch(`${FB_BASE}/${pageId}?fields=access_token&access_token=${token}`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB getPageToken failed: ${body}`, res.status);
    return JSON.parse(body);
  }
 
  async getUserInfo(token: FacebookToken): Promise<FacebookUserInfo> {
    const res = await fetch(`${FB_BASE}/me?access_token=${token.accessToken}`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB getUserInfo failed: ${body}`, res.status);
    return JSON.parse(body);
  }
 
  async createPost(post: NewFacebookPost, token: string): Promise<NewFacebookPost> {
    const params = new URLSearchParams({ access_token: token, message: post.content });
    const res = await fetch(`${FB_BASE}/me/posts`, { method: 'POST', body: params });
    if (!res.ok) {
      const text = await res.text();
      throw new ChannelApiError(`FB createPost failed: ${text}`, res.status);
    }
    return post;
  }
 
  async createPagePost(pageId: string, post: NewSocialPostRequestModel, token: string): Promise<NewSocialPostResponseModel> {
    const formData = new URLSearchParams({ access_token: token, message: post.content });
    if (post.medias?.[0]?.url) formData.set('link', post.medias[0].url);
    const res = await fetch(`${FB_BASE}/${pageId}/feed`, { method: 'POST', body: formData });
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB createPagePost failed: ${body}`, res.status);
    return JSON.parse(body);
  }
 
  async getPostMetrics(postId: string, token: string): Promise<FacebookPostMetrics> {
    const res = await fetch(`${FB_BASE}/${postId}/insights?metric=post_impressions,post_clicks,post_reactions_by_type_total&access_token=${token}`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB getPostMetrics failed: ${body}`, res.status);
    return JSON.parse(body);
  }
 
  async getPageMetrics(pageId: string, token: string): Promise<FacebookPageMetrics> {
    const res = await fetch(`${FB_BASE}/${pageId}/insights?metric=page_impressions,page_fans&access_token=${token}`);
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB getPageMetrics failed: ${body}`, res.status);
    return JSON.parse(body);
  }
 
  async getMetaCampaignPerformanceSummaryAsync(
    adAccountId: string, accessToken: string, startDate: Date, endDate: Date
  ): Promise<MetaAdsInsightsResponse> {
    const since = Math.floor(startDate.getTime() / 1000);
    const until = Math.floor(endDate.getTime() / 1000);
    const res = await fetch(
      `${FB_BASE}/v19.0/act_${adAccountId}/insights?fields=campaign_name,impressions,clicks,spend,reach,cpc,ctr&time_range={"since":"${startDate.toISOString().split('T')[0]}","until":"${endDate.toISOString().split('T')[0]}"}&level=campaign&access_token=${accessToken}`
    );
    const body = await res.text();
    if (!res.ok) throw new ChannelApiError(`FB getCampaignPerformance failed: ${body}`, res.status);
    return JSON.parse(body);
  }
}
 
// Usage:
const fb = new FacebookService();
const redirectUrl = fb.authorize('https://yourdomain.com/callback', 'state-xyz');
const shortToken = await fb.authorizeCallback(code, 'https://yourdomain.com/callback');
const longToken = await fb.getLongLivedToken(shortToken.accessToken);
const pages = await fb.getFacebookPages(longToken.accessToken);
const pageToken = await fb.getPageToken(pages.data[0].id, longToken.accessToken);
await fb.createPagePost(pages.data[0].id, { content: 'Hello World!' }, pageToken.accessToken);

instagram_business_basic, instagram_business_content_publish,
instagram_business_manage_comments, instagram_business_manage_messages,
instagram_business_manage_insights