@hasna/connectors 0.0.1

package/connectors/connect-xads/src/api/client.ts

@@ -0,0 +1,315 @@
+import * as crypto from 'crypto';
+import type { XAdsConfig } from '../types';
+
+const DEFAULT_BASE_URL = 'https://ads-api.twitter.com';
+const API_VERSION = '12'; // Twitter Ads API version
+
+export interface XAdsClientConfig {
+  consumerKey: string;
+  consumerSecret: string;
+  accessToken?: string;
+  accessTokenSecret?: string;
+  baseUrl?: string;
+}
+
+export class XAdsClient {
+  private readonly consumerKey: string;
+  private readonly consumerSecret: string;
+  private readonly accessToken?: string;
+  private readonly accessTokenSecret?: string;
+  private readonly baseUrl: string;
+
+  constructor(config: XAdsClientConfig) {
+    this.consumerKey = config.consumerKey;
+    this.consumerSecret = config.consumerSecret;
+    this.accessToken = config.accessToken;
+    this.accessTokenSecret = config.accessTokenSecret;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  // OAuth 1.0a signature generation
+  private generateOAuthSignature(
+    method: string,
+    url: string,
+    params: Record<string, string>,
+    tokenSecret: string = ''
+  ): string {
+    // Sort parameters alphabetically
+    const sortedParams = Object.keys(params)
+      .sort()
+      .map((key) => `${this.percentEncode(key)}=${this.percentEncode(params[key])}`)
+      .join('&');
+
+    // Create signature base string
+    const signatureBaseString = [
+      method.toUpperCase(),
+      this.percentEncode(url),
+      this.percentEncode(sortedParams),
+    ].join('&');
+
+    // Create signing key
+    const signingKey = `${this.percentEncode(this.consumerSecret)}&${this.percentEncode(tokenSecret)}`;
+
+    // Generate HMAC-SHA1 signature
+    const hmac = crypto.createHmac('sha1', signingKey);
+    hmac.update(signatureBaseString);
+    return hmac.digest('base64');
+  }
+
+  private percentEncode(str: string): string {
+    return encodeURIComponent(str)
+      .replace(/!/g, '%21')
+      .replace(/\*/g, '%2A')
+      .replace(/'/g, '%27')
+      .replace(/\(/g, '%28')
+      .replace(/\)/g, '%29');
+  }
+
+  private generateNonce(): string {
+    return crypto.randomBytes(16).toString('hex');
+  }
+
+  private generateTimestamp(): string {
+    return Math.floor(Date.now() / 1000).toString();
+  }
+
+  // Build OAuth Authorization header
+  private buildAuthHeader(
+    method: string,
+    url: string,
+    additionalParams: Record<string, string> = {}
+  ): string {
+    if (!this.accessToken || !this.accessTokenSecret) {
+      throw new Error('Access token and secret required for authenticated requests');
+    }
+
+    const oauthParams: Record<string, string> = {
+      oauth_consumer_key: this.consumerKey,
+      oauth_nonce: this.generateNonce(),
+      oauth_signature_method: 'HMAC-SHA1',
+      oauth_timestamp: this.generateTimestamp(),
+      oauth_token: this.accessToken,
+      oauth_version: '1.0',
+    };
+
+    // Combine OAuth params with additional params for signature
+    const allParams = { ...oauthParams, ...additionalParams };
+
+    // Generate signature
+    const signature = this.generateOAuthSignature(
+      method,
+      url,
+      allParams,
+      this.accessTokenSecret
+    );
+    oauthParams.oauth_signature = signature;
+
+    // Build Authorization header
+    const authHeader = Object.keys(oauthParams)
+      .sort()
+      .map((key) => `${this.percentEncode(key)}="${this.percentEncode(oauthParams[key])}"`)
+      .join(', ');
+
+    return `OAuth ${authHeader}`;
+  }
+
+  // Make authenticated request
+  async request<T>(
+    method: string,
+    endpoint: string,
+    options: {
+      params?: Record<string, string | number | boolean | undefined>;
+      body?: Record<string, unknown>;
+    } = {}
+  ): Promise<T> {
+    // Build URL with version
+    const urlPath = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    const versionedPath = urlPath.startsWith(`/${API_VERSION}`) ? urlPath : `/${API_VERSION}${urlPath}`;
+    const baseUrl = `${this.baseUrl}${versionedPath}`;
+
+    // Build query string
+    const queryParams: Record<string, string> = {};
+    if (options.params) {
+      for (const [key, value] of Object.entries(options.params)) {
+        if (value !== undefined) {
+          queryParams[key] = String(value);
+        }
+      }
+    }
+
+    const queryString = Object.keys(queryParams).length > 0
+      ? '?' + Object.entries(queryParams)
+          .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+          .join('&')
+      : '';
+
+    const fullUrl = `${baseUrl}${queryString}`;
+
+    // For OAuth signature, we need URL without query string for POST with body
+    const signatureUrl = baseUrl;
+
+    // Get params for signature (query params for GET, empty for POST with JSON body)
+    const signatureParams = method.toUpperCase() === 'GET' ? queryParams : {};
+
+    // Build auth header
+    const authHeader = this.buildAuthHeader(method, signatureUrl, signatureParams);
+
+    // Make request
+    const headers: Record<string, string> = {
+      Authorization: authHeader,
+      'Content-Type': 'application/json',
+    };
+
+    const fetchOptions: RequestInit = {
+      method: method.toUpperCase(),
+      headers,
+    };
+
+    if (options.body && ['POST', 'PUT', 'PATCH'].includes(method.toUpperCase())) {
+      fetchOptions.body = JSON.stringify(options.body);
+    }
+
+    const response = await fetch(fullUrl, fetchOptions);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      let errorMessage = `API Error: ${response.status} ${response.statusText}`;
+      try {
+        const errorJson = JSON.parse(errorText);
+        if (errorJson.errors) {
+          errorMessage = errorJson.errors.map((e: { message: string }) => e.message).join(', ');
+        } else if (errorJson.error) {
+          errorMessage = errorJson.error;
+        }
+      } catch {
+        if (errorText) {
+          errorMessage = errorText;
+        }
+      }
+      throw new Error(errorMessage);
+    }
+
+    const data = await response.json();
+    return data as T;
+  }
+
+  // HTTP method shortcuts
+  async get<T>(endpoint: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('GET', endpoint, { params });
+  }
+
+  async post<T>(endpoint: string, body?: Record<string, unknown>, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('POST', endpoint, { body, params });
+  }
+
+  async put<T>(endpoint: string, body?: Record<string, unknown>, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('PUT', endpoint, { body, params });
+  }
+
+  async delete<T>(endpoint: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('DELETE', endpoint, { params });
+  }
+
+  // OAuth helper methods for PIN-based auth flow
+  async getRequestToken(): Promise<{ oauthToken: string; oauthTokenSecret: string }> {
+    const requestTokenUrl = 'https://api.twitter.com/oauth/request_token';
+
+    const oauthParams: Record<string, string> = {
+      oauth_callback: 'oob',
+      oauth_consumer_key: this.consumerKey,
+      oauth_nonce: this.generateNonce(),
+      oauth_signature_method: 'HMAC-SHA1',
+      oauth_timestamp: this.generateTimestamp(),
+      oauth_version: '1.0',
+    };
+
+    const signature = this.generateOAuthSignature('POST', requestTokenUrl, oauthParams);
+    oauthParams.oauth_signature = signature;
+
+    const authHeader = Object.keys(oauthParams)
+      .sort()
+      .map((key) => `${this.percentEncode(key)}="${this.percentEncode(oauthParams[key])}"`)
+      .join(', ');
+
+    const response = await fetch(requestTokenUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `OAuth ${authHeader}`,
+      },
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Failed to get request token: ${text}`);
+    }
+
+    const text = await response.text();
+    const params = new URLSearchParams(text);
+
+    return {
+      oauthToken: params.get('oauth_token') || '',
+      oauthTokenSecret: params.get('oauth_token_secret') || '',
+    };
+  }
+
+  getAuthorizeUrl(oauthToken: string): string {
+    return `https://api.twitter.com/oauth/authorize?oauth_token=${oauthToken}`;
+  }
+
+  async getAccessToken(
+    oauthToken: string,
+    oauthTokenSecret: string,
+    pin: string
+  ): Promise<{ accessToken: string; accessTokenSecret: string; userId: string; screenName: string }> {
+    const accessTokenUrl = 'https://api.twitter.com/oauth/access_token';
+
+    const oauthParams: Record<string, string> = {
+      oauth_consumer_key: this.consumerKey,
+      oauth_nonce: this.generateNonce(),
+      oauth_signature_method: 'HMAC-SHA1',
+      oauth_timestamp: this.generateTimestamp(),
+      oauth_token: oauthToken,
+      oauth_verifier: pin,
+      oauth_version: '1.0',
+    };
+
+    const signature = this.generateOAuthSignature('POST', accessTokenUrl, oauthParams, oauthTokenSecret);
+    oauthParams.oauth_signature = signature;
+
+    const authHeader = Object.keys(oauthParams)
+      .sort()
+      .map((key) => `${this.percentEncode(key)}="${this.percentEncode(oauthParams[key])}"`)
+      .join(', ');
+
+    const response = await fetch(accessTokenUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `OAuth ${authHeader}`,
+      },
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Failed to get access token: ${text}`);
+    }
+
+    const text = await response.text();
+    const params = new URLSearchParams(text);
+
+    return {
+      accessToken: params.get('oauth_token') || '',
+      accessTokenSecret: params.get('oauth_token_secret') || '',
+      userId: params.get('user_id') || '',
+      screenName: params.get('screen_name') || '',
+    };
+  }
+
+  // Getters
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  hasUserTokens(): boolean {
+    return !!(this.accessToken && this.accessTokenSecret);
+  }
+}

package/connectors/connect-xads/src/api/index.ts

@@ -0,0 +1,91 @@
+import { XAdsClient, type XAdsClientConfig } from './client';
+import { AccountsApi } from './accounts';
+import { CampaignsApi } from './campaigns';
+import { LineItemsApi } from './line-items';
+import { PromotedTweetsApi } from './promoted-tweets';
+import { TargetingApi } from './targeting';
+import { AudiencesApi } from './audiences';
+import { AnalyticsApi } from './analytics';
+import { MediaApi } from './media';
+
+/**
+ * Main X Ads Connector class
+ * Provides access to all Twitter/X Ads API endpoints
+ */
+export class XAds {
+  private readonly client: XAdsClient;
+
+  // API modules
+  public readonly accounts: AccountsApi;
+  public readonly campaigns: CampaignsApi;
+  public readonly lineItems: LineItemsApi;
+  public readonly promotedTweets: PromotedTweetsApi;
+  public readonly targeting: TargetingApi;
+  public readonly audiences: AudiencesApi;
+  public readonly analytics: AnalyticsApi;
+  public readonly media: MediaApi;
+
+  constructor(config: XAdsClientConfig) {
+    this.client = new XAdsClient(config);
+    this.accounts = new AccountsApi(this.client);
+    this.campaigns = new CampaignsApi(this.client);
+    this.lineItems = new LineItemsApi(this.client);
+    this.promotedTweets = new PromotedTweetsApi(this.client);
+    this.targeting = new TargetingApi(this.client);
+    this.audiences = new AudiencesApi(this.client);
+    this.analytics = new AnalyticsApi(this.client);
+    this.media = new MediaApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   */
+  static fromEnv(): XAds {
+    const consumerKey = process.env.X_ADS_CONSUMER_KEY;
+    const consumerSecret = process.env.X_ADS_CONSUMER_SECRET;
+    const accessToken = process.env.X_ADS_ACCESS_TOKEN;
+    const accessTokenSecret = process.env.X_ADS_ACCESS_TOKEN_SECRET;
+
+    if (!consumerKey || !consumerSecret) {
+      throw new Error('X_ADS_CONSUMER_KEY and X_ADS_CONSUMER_SECRET environment variables are required');
+    }
+
+    return new XAds({
+      consumerKey,
+      consumerSecret,
+      accessToken,
+      accessTokenSecret,
+    });
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): XAdsClient {
+    return this.client;
+  }
+
+  /**
+   * Get base URL
+   */
+  getBaseUrl(): string {
+    return this.client.getBaseUrl();
+  }
+
+  /**
+   * Check if user tokens are configured
+   */
+  hasUserTokens(): boolean {
+    return this.client.hasUserTokens();
+  }
+}
+
+export { XAdsClient } from './client';
+export { AccountsApi } from './accounts';
+export { CampaignsApi } from './campaigns';
+export { LineItemsApi } from './line-items';
+export { PromotedTweetsApi } from './promoted-tweets';
+export { TargetingApi } from './targeting';
+export { AudiencesApi } from './audiences';
+export { AnalyticsApi } from './analytics';
+export { MediaApi } from './media';

package/connectors/connect-xads/src/api/line-items.ts

@@ -0,0 +1,126 @@
+import type { XAdsClient } from './client';
+import type {
+  LineItem,
+  CreateLineItemParams,
+  UpdateLineItemParams,
+  ListResponse,
+  PaginationParams,
+} from '../types';
+
+/**
+ * Line Items (Ad Groups) API
+ */
+export class LineItemsApi {
+  constructor(private client: XAdsClient) {}
+
+  /**
+   * List all line items for an account
+   */
+  async list(
+    accountId: string,
+    params?: PaginationParams & {
+      line_item_ids?: string[];
+      campaign_ids?: string[];
+      funding_instrument_ids?: string[];
+    }
+  ): Promise<ListResponse<LineItem>> {
+    return this.client.get<ListResponse<LineItem>>(`/accounts/${accountId}/line_items`, {
+      cursor: params?.cursor,
+      count: params?.count,
+      sort_by: params?.sort_by?.join(','),
+      with_deleted: params?.with_deleted,
+      with_total_count: params?.with_total_count,
+      line_item_ids: params?.line_item_ids?.join(','),
+      campaign_ids: params?.campaign_ids?.join(','),
+      funding_instrument_ids: params?.funding_instrument_ids?.join(','),
+    });
+  }
+
+  /**
+   * Get a specific line item
+   */
+  async get(
+    accountId: string,
+    lineItemId: string,
+    withDeleted?: boolean
+  ): Promise<{ data: LineItem }> {
+    return this.client.get<{ data: LineItem }>(
+      `/accounts/${accountId}/line_items/${lineItemId}`,
+      { with_deleted: withDeleted }
+    );
+  }
+
+  /**
+   * Create a new line item
+   */
+  async create(accountId: string, params: CreateLineItemParams): Promise<{ data: LineItem }> {
+    return this.client.post<{ data: LineItem }>(`/accounts/${accountId}/line_items`, {
+      campaign_id: params.campaign_id,
+      name: params.name,
+      objective: params.objective,
+      placements: params.placements,
+      bid_amount_local_micro: params.bid_amount_local_micro,
+      bid_strategy: params.bid_strategy || 'AUTO',
+      charge_by: params.charge_by,
+      optimization: params.optimization,
+      target_cpa_local_micro: params.target_cpa_local_micro,
+      total_budget_amount_local_micro: params.total_budget_amount_local_micro,
+      start_time: params.start_time,
+      end_time: params.end_time,
+      entity_status: params.entity_status || 'PAUSED',
+      automatically_select_bid: params.automatically_select_bid,
+      advertiser_domain: params.advertiser_domain,
+      categories: params.categories,
+      primary_web_event_tag: params.primary_web_event_tag,
+    });
+  }
+
+  /**
+   * Update a line item
+   */
+  async update(
+    accountId: string,
+    lineItemId: string,
+    params: UpdateLineItemParams
+  ): Promise<{ data: LineItem }> {
+    return this.client.put<{ data: LineItem }>(
+      `/accounts/${accountId}/line_items/${lineItemId}`,
+      {
+        name: params.name,
+        bid_amount_local_micro: params.bid_amount_local_micro,
+        bid_strategy: params.bid_strategy,
+        target_cpa_local_micro: params.target_cpa_local_micro,
+        total_budget_amount_local_micro: params.total_budget_amount_local_micro,
+        start_time: params.start_time,
+        end_time: params.end_time,
+        entity_status: params.entity_status,
+        automatically_select_bid: params.automatically_select_bid,
+        advertiser_domain: params.advertiser_domain,
+        primary_web_event_tag: params.primary_web_event_tag,
+      }
+    );
+  }
+
+  /**
+   * Delete (soft delete) a line item
+   */
+  async delete(accountId: string, lineItemId: string): Promise<{ data: LineItem }> {
+    return this.client.delete<{ data: LineItem }>(
+      `/accounts/${accountId}/line_items/${lineItemId}`
+    );
+  }
+
+  /**
+   * Pause a line item
+   */
+  async pause(accountId: string, lineItemId: string): Promise<{ data: LineItem }> {
+    return this.update(accountId, lineItemId, { entity_status: 'PAUSED' });
+  }
+
+  /**
+   * Activate a line item
+   */
+  async activate(accountId: string, lineItemId: string): Promise<{ data: LineItem }> {
+    return this.update(accountId, lineItemId, { entity_status: 'ACTIVE' });
+  }
+}

package/connectors/connect-xads/src/api/media.ts

@@ -0,0 +1,96 @@
+import type { XAdsClient } from './client';
+import type {
+  MediaCreative,
+  CreateMediaCreativeParams,
+  ListResponse,
+  PaginationParams,
+} from '../types';
+
+/**
+ * Media Creatives API
+ */
+export class MediaApi {
+  constructor(private client: XAdsClient) {}
+
+  /**
+   * List all media creatives for an account
+   */
+  async list(
+    accountId: string,
+    params?: PaginationParams & {
+      media_creative_ids?: string[];
+      line_item_ids?: string[];
+    }
+  ): Promise<ListResponse<MediaCreative>> {
+    return this.client.get<ListResponse<MediaCreative>>(
+      `/accounts/${accountId}/media_creatives`,
+      {
+        cursor: params?.cursor,
+        count: params?.count,
+        with_deleted: params?.with_deleted,
+        with_total_count: params?.with_total_count,
+        media_creative_ids: params?.media_creative_ids?.join(','),
+        line_item_ids: params?.line_item_ids?.join(','),
+      }
+    );
+  }
+
+  /**
+   * Get a specific media creative
+   */
+  async get(
+    accountId: string,
+    mediaCreativeId: string,
+    withDeleted?: boolean
+  ): Promise<{ data: MediaCreative }> {
+    return this.client.get<{ data: MediaCreative }>(
+      `/accounts/${accountId}/media_creatives/${mediaCreativeId}`,
+      { with_deleted: withDeleted }
+    );
+  }
+
+  /**
+   * Create a media creative
+   */
+  async create(
+    accountId: string,
+    params: CreateMediaCreativeParams
+  ): Promise<{ data: MediaCreative }> {
+    return this.client.post<{ data: MediaCreative }>(
+      `/accounts/${accountId}/media_creatives`,
+      {
+        line_item_id: params.line_item_id,
+        media_key: params.media_key,
+        landing_url: params.landing_url,
+      }
+    );
+  }
+
+  /**
+   * Delete a media creative
+   */
+  async delete(accountId: string, mediaCreativeId: string): Promise<{ data: MediaCreative }> {
+    return this.client.delete<{ data: MediaCreative }>(
+      `/accounts/${accountId}/media_creatives/${mediaCreativeId}`
+    );
+  }
+
+  /**
+   * Get media library (uploaded media)
+   */
+  async getLibrary(
+    accountId: string,
+    params?: PaginationParams & {
+      media_type?: 'IMAGE' | 'VIDEO' | 'GIF';
+    }
+  ): Promise<ListResponse<{ media_key: string; media_type: string; media_url: string }>> {
+    return this.client.get<ListResponse<{ media_key: string; media_type: string; media_url: string }>>(
+      `/accounts/${accountId}/media_library`,
+      {
+        cursor: params?.cursor,
+        count: params?.count,
+        media_type: params?.media_type,
+      }
+    );
+  }
+}