@hasna/connectors 0.0.1

package/connectors/connect-xads/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/connect-xads",
+  "version": "0.0.1",
+  "description": "Twitter/X Ads API connector CLI - Manage ad campaigns, promoted tweets, targeting, and analytics",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "connect-xads": "./bin/index.js"
+  },
+  "scripts": {
+    "dev": "bun run ./src/cli/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "twitter",
+    "x",
+    "ads",
+    "advertising",
+    "campaigns",
+    "promoted-tweets",
+    "analytics",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "CLAUDE.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/opensource-connectors.git"
+  }
+}

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

@@ -0,0 +1,70 @@
+import type { XAdsClient } from './client';
+import type { AdAccount, FundingInstrument, ListResponse, PaginationParams } from '../types';
+
+/**
+ * Ad Accounts API
+ */
+export class AccountsApi {
+  constructor(private client: XAdsClient) {}
+
+  /**
+   * List all ad accounts accessible to the authenticated user
+   */
+  async list(params?: PaginationParams): Promise<ListResponse<AdAccount>> {
+    return this.client.get<ListResponse<AdAccount>>('/accounts', {
+      cursor: params?.cursor,
+      count: params?.count,
+      sort_by: params?.sort_by?.join(','),
+      with_deleted: params?.with_deleted,
+      with_total_count: params?.with_total_count,
+    });
+  }
+
+  /**
+   * Get a specific ad account by ID
+   */
+  async get(accountId: string, withDeleted?: boolean): Promise<{ data: AdAccount }> {
+    return this.client.get<{ data: AdAccount }>(`/accounts/${accountId}`, {
+      with_deleted: withDeleted,
+    });
+  }
+
+  /**
+   * Get account features/capabilities
+   */
+  async getFeatures(accountId: string): Promise<{ data: string[] }> {
+    return this.client.get<{ data: string[] }>(`/accounts/${accountId}/features`);
+  }
+
+  /**
+   * List funding instruments for an account
+   */
+  async listFundingInstruments(
+    accountId: string,
+    params?: PaginationParams
+  ): Promise<ListResponse<FundingInstrument>> {
+    return this.client.get<ListResponse<FundingInstrument>>(
+      `/accounts/${accountId}/funding_instruments`,
+      {
+        cursor: params?.cursor,
+        count: params?.count,
+        with_deleted: params?.with_deleted,
+        with_total_count: params?.with_total_count,
+      }
+    );
+  }
+
+  /**
+   * Get a specific funding instrument
+   */
+  async getFundingInstrument(
+    accountId: string,
+    fundingInstrumentId: string,
+    withDeleted?: boolean
+  ): Promise<{ data: FundingInstrument }> {
+    return this.client.get<{ data: FundingInstrument }>(
+      `/accounts/${accountId}/funding_instruments/${fundingInstrumentId}`,
+      { with_deleted: withDeleted }
+    );
+  }
+}

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

@@ -0,0 +1,165 @@
+import type { XAdsClient } from './client';
+import type {
+  AnalyticsParams,
+  AnalyticsResponse,
+  ReachEstimateParams,
+  ReachEstimate,
+  Granularity,
+  MetricGroup,
+} from '../types';
+
+/**
+ * Analytics API
+ */
+export class AnalyticsApi {
+  constructor(private client: XAdsClient) {}
+
+  /**
+   * Get campaign analytics
+   */
+  async getCampaignStats(
+    accountId: string,
+    campaignIds: string[],
+    params: {
+      start_time: string;
+      end_time: string;
+      granularity?: Granularity;
+      metric_groups?: MetricGroup[];
+      placement?: string;
+    }
+  ): Promise<AnalyticsResponse> {
+    return this.client.get<AnalyticsResponse>(
+      `/stats/accounts/${accountId}/campaigns`,
+      {
+        campaign_ids: campaignIds.join(','),
+        start_time: params.start_time,
+        end_time: params.end_time,
+        granularity: params.granularity || 'TOTAL',
+        metric_groups: params.metric_groups?.join(',') || 'ENGAGEMENT',
+        placement: params.placement,
+      }
+    );
+  }
+
+  /**
+   * Get line item analytics
+   */
+  async getLineItemStats(
+    accountId: string,
+    lineItemIds: string[],
+    params: {
+      start_time: string;
+      end_time: string;
+      granularity?: Granularity;
+      metric_groups?: MetricGroup[];
+      placement?: string;
+    }
+  ): Promise<AnalyticsResponse> {
+    return this.client.get<AnalyticsResponse>(
+      `/stats/accounts/${accountId}/line_items`,
+      {
+        line_item_ids: lineItemIds.join(','),
+        start_time: params.start_time,
+        end_time: params.end_time,
+        granularity: params.granularity || 'TOTAL',
+        metric_groups: params.metric_groups?.join(',') || 'ENGAGEMENT',
+        placement: params.placement,
+      }
+    );
+  }
+
+  /**
+   * Get promoted tweet analytics
+   */
+  async getPromotedTweetStats(
+    accountId: string,
+    promotedTweetIds: string[],
+    params: {
+      start_time: string;
+      end_time: string;
+      granularity?: Granularity;
+      metric_groups?: MetricGroup[];
+      placement?: string;
+    }
+  ): Promise<AnalyticsResponse> {
+    return this.client.get<AnalyticsResponse>(
+      `/stats/accounts/${accountId}/promoted_tweets`,
+      {
+        promoted_tweet_ids: promotedTweetIds.join(','),
+        start_time: params.start_time,
+        end_time: params.end_time,
+        granularity: params.granularity || 'TOTAL',
+        metric_groups: params.metric_groups?.join(',') || 'ENGAGEMENT',
+        placement: params.placement,
+      }
+    );
+  }
+
+  /**
+   * Get account-level analytics
+   */
+  async getAccountStats(
+    accountId: string,
+    params: {
+      start_time: string;
+      end_time: string;
+      granularity?: Granularity;
+      metric_groups?: MetricGroup[];
+    }
+  ): Promise<AnalyticsResponse> {
+    return this.client.get<AnalyticsResponse>(
+      `/stats/accounts/${accountId}`,
+      {
+        start_time: params.start_time,
+        end_time: params.end_time,
+        granularity: params.granularity || 'TOTAL',
+        metric_groups: params.metric_groups?.join(',') || 'ENGAGEMENT',
+      }
+    );
+  }
+
+  /**
+   * Get reach estimate for targeting criteria
+   */
+  async getReachEstimate(
+    accountId: string,
+    params: ReachEstimateParams
+  ): Promise<{ data: ReachEstimate }> {
+    return this.client.get<{ data: ReachEstimate }>(
+      `/accounts/${accountId}/reach_estimate`,
+      {
+        objective: params.objective,
+        bid_amount_local_micro: params.bid_amount_local_micro,
+        currency: params.currency,
+        campaign_daily_budget_amount_local_micro: params.campaign_daily_budget_amount_local_micro,
+        similar_to_followers_of_users: params.similar_to_followers_of_users?.join(','),
+        locations: params.locations?.join(','),
+        interests: params.interests?.join(','),
+        gender: params.gender,
+        platforms: params.platforms?.join(','),
+        tailored_audiences: params.tailored_audiences?.join(','),
+        age_buckets: params.age_buckets?.join(','),
+        languages: params.languages?.join(','),
+      }
+    );
+  }
+
+  /**
+   * Get active entities count
+   */
+  async getActiveEntities(
+    accountId: string,
+    params: {
+      start_time: string;
+      end_time: string;
+    }
+  ): Promise<{ data: { campaigns: number; line_items: number; promoted_tweets: number } }> {
+    return this.client.get<{ data: { campaigns: number; line_items: number; promoted_tweets: number } }>(
+      `/stats/accounts/${accountId}/active_entities`,
+      {
+        start_time: params.start_time,
+        end_time: params.end_time,
+      }
+    );
+  }
+}

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

@@ -0,0 +1,143 @@
+import type { XAdsClient } from './client';
+import type {
+  TailoredAudience,
+  CreateTailoredAudienceParams,
+  ListResponse,
+  PaginationParams,
+} from '../types';
+
+/**
+ * Tailored Audiences (Custom Audiences) API
+ */
+export class AudiencesApi {
+  constructor(private client: XAdsClient) {}
+
+  /**
+   * List all tailored audiences for an account
+   */
+  async list(
+    accountId: string,
+    params?: PaginationParams & {
+      tailored_audience_ids?: string[];
+    }
+  ): Promise<ListResponse<TailoredAudience>> {
+    return this.client.get<ListResponse<TailoredAudience>>(
+      `/accounts/${accountId}/tailored_audiences`,
+      {
+        cursor: params?.cursor,
+        count: params?.count,
+        with_deleted: params?.with_deleted,
+        with_total_count: params?.with_total_count,
+        tailored_audience_ids: params?.tailored_audience_ids?.join(','),
+      }
+    );
+  }
+
+  /**
+   * Get a specific tailored audience
+   */
+  async get(
+    accountId: string,
+    audienceId: string,
+    withDeleted?: boolean
+  ): Promise<{ data: TailoredAudience }> {
+    return this.client.get<{ data: TailoredAudience }>(
+      `/accounts/${accountId}/tailored_audiences/${audienceId}`,
+      { with_deleted: withDeleted }
+    );
+  }
+
+  /**
+   * Create a new tailored audience
+   */
+  async create(
+    accountId: string,
+    params: CreateTailoredAudienceParams
+  ): Promise<{ data: TailoredAudience }> {
+    return this.client.post<{ data: TailoredAudience }>(
+      `/accounts/${accountId}/tailored_audiences`,
+      {
+        name: params.name,
+        list_type: params.list_type,
+      }
+    );
+  }
+
+  /**
+   * Delete a tailored audience
+   */
+  async delete(accountId: string, audienceId: string): Promise<{ data: TailoredAudience }> {
+    return this.client.delete<{ data: TailoredAudience }>(
+      `/accounts/${accountId}/tailored_audiences/${audienceId}`
+    );
+  }
+
+  /**
+   * Get users for a tailored audience (for lookup)
+   */
+  async getUsers(
+    accountId: string,
+    audienceId: string
+  ): Promise<{ data: { users_count: number } }> {
+    return this.client.get<{ data: { users_count: number } }>(
+      `/accounts/${accountId}/tailored_audiences/${audienceId}/users`
+    );
+  }
+
+  /**
+   * Add users to a tailored audience
+   * Note: Users should be hashed before sending
+   */
+  async addUsers(
+    accountId: string,
+    audienceId: string,
+    users: string[],
+    listType: 'EMAIL' | 'DEVICE_ID' | 'TWITTER_ID' | 'HANDLE' | 'PHONE_NUMBER'
+  ): Promise<{ data: { success_count: number; total_count: number } }> {
+    return this.client.post<{ data: { success_count: number; total_count: number } }>(
+      `/accounts/${accountId}/tailored_audiences/${audienceId}/users`,
+      {
+        operation_type: 'Update',
+        users,
+        list_type: listType,
+      }
+    );
+  }
+
+  /**
+   * Remove users from a tailored audience
+   */
+  async removeUsers(
+    accountId: string,
+    audienceId: string,
+    users: string[],
+    listType: 'EMAIL' | 'DEVICE_ID' | 'TWITTER_ID' | 'HANDLE' | 'PHONE_NUMBER'
+  ): Promise<{ data: { success_count: number; total_count: number } }> {
+    return this.client.post<{ data: { success_count: number; total_count: number } }>(
+      `/accounts/${accountId}/tailored_audiences/${audienceId}/users`,
+      {
+        operation_type: 'Delete',
+        users,
+        list_type: listType,
+      }
+    );
+  }
+
+  /**
+   * Create a lookalike audience from an existing audience
+   */
+  async createLookalike(
+    accountId: string,
+    sourceAudienceId: string,
+    name: string
+  ): Promise<{ data: TailoredAudience }> {
+    return this.client.post<{ data: TailoredAudience }>(
+      `/accounts/${accountId}/tailored_audiences`,
+      {
+        name,
+        tailored_audience_type: 'LOOKALIKE',
+        source_audience_id: sourceAudienceId,
+      }
+    );
+  }
+}

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

@@ -0,0 +1,113 @@
+import type { XAdsClient } from './client';
+import type {
+  Campaign,
+  CreateCampaignParams,
+  UpdateCampaignParams,
+  ListResponse,
+  PaginationParams,
+} from '../types';
+
+/**
+ * Campaigns API
+ */
+export class CampaignsApi {
+  constructor(private client: XAdsClient) {}
+
+  /**
+   * List all campaigns for an account
+   */
+  async list(
+    accountId: string,
+    params?: PaginationParams & {
+      campaign_ids?: string[];
+      funding_instrument_ids?: string[];
+    }
+  ): Promise<ListResponse<Campaign>> {
+    return this.client.get<ListResponse<Campaign>>(`/accounts/${accountId}/campaigns`, {
+      cursor: params?.cursor,
+      count: params?.count,
+      sort_by: params?.sort_by?.join(','),
+      with_deleted: params?.with_deleted,
+      with_total_count: params?.with_total_count,
+      campaign_ids: params?.campaign_ids?.join(','),
+      funding_instrument_ids: params?.funding_instrument_ids?.join(','),
+    });
+  }
+
+  /**
+   * Get a specific campaign
+   */
+  async get(
+    accountId: string,
+    campaignId: string,
+    withDeleted?: boolean
+  ): Promise<{ data: Campaign }> {
+    return this.client.get<{ data: Campaign }>(
+      `/accounts/${accountId}/campaigns/${campaignId}`,
+      { with_deleted: withDeleted }
+    );
+  }
+
+  /**
+   * Create a new campaign
+   */
+  async create(accountId: string, params: CreateCampaignParams): Promise<{ data: Campaign }> {
+    return this.client.post<{ data: Campaign }>(`/accounts/${accountId}/campaigns`, {
+      name: params.name,
+      funding_instrument_id: params.funding_instrument_id,
+      daily_budget_amount_local_micro: params.daily_budget_amount_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',
+      standard_delivery: params.standard_delivery,
+      purchase_order_number: params.purchase_order_number,
+    });
+  }
+
+  /**
+   * Update a campaign
+   */
+  async update(
+    accountId: string,
+    campaignId: string,
+    params: UpdateCampaignParams
+  ): Promise<{ data: Campaign }> {
+    return this.client.put<{ data: Campaign }>(
+      `/accounts/${accountId}/campaigns/${campaignId}`,
+      {
+        name: params.name,
+        daily_budget_amount_local_micro: params.daily_budget_amount_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,
+        standard_delivery: params.standard_delivery,
+        purchase_order_number: params.purchase_order_number,
+      }
+    );
+  }
+
+  /**
+   * Delete (soft delete) a campaign
+   */
+  async delete(accountId: string, campaignId: string): Promise<{ data: Campaign }> {
+    return this.client.delete<{ data: Campaign }>(
+      `/accounts/${accountId}/campaigns/${campaignId}`
+    );
+  }
+
+  /**
+   * Pause a campaign
+   */
+  async pause(accountId: string, campaignId: string): Promise<{ data: Campaign }> {
+    return this.update(accountId, campaignId, { entity_status: 'PAUSED' });
+  }
+
+  /**
+   * Activate a campaign
+   */
+  async activate(accountId: string, campaignId: string): Promise<{ data: Campaign }> {
+    return this.update(accountId, campaignId, { entity_status: 'ACTIVE' });
+  }
+}