@hasna/connectors 0.0.1

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

@@ -0,0 +1,246 @@
+import type { TikTokClient } from './client';
+import type {
+  Audience,
+  AudienceCreateParams,
+  AudienceUpdateParams,
+  AudienceListParams,
+  LookalikeSpec,
+  PaginatedData,
+} from '../types';
+
+/**
+ * TikTok Audiences API
+ * Create and manage custom audiences and lookalike audiences
+ */
+export class AudiencesApi {
+  constructor(private readonly client: TikTokClient) {}
+
+  /**
+   * List audiences
+   * GET /dmp/custom_audience/get/
+   */
+  async list(params: AudienceListParams): Promise<PaginatedData<Audience>> {
+    return this.client.get<PaginatedData<Audience>>('/dmp/custom_audience/get/', {
+      advertiser_id: params.advertiser_id,
+      custom_audience_ids: params.filtering?.audience_ids,
+      page: params.page,
+      page_size: params.page_size,
+    });
+  }
+
+  /**
+   * Get a single audience by ID
+   */
+  async get(advertiserId: string, audienceId: string): Promise<Audience> {
+    const response = await this.list({
+      advertiser_id: advertiserId,
+      filtering: { audience_ids: [audienceId] },
+    });
+    if (!response.list || response.list.length === 0) {
+      throw new Error(`Audience ${audienceId} not found`);
+    }
+    return response.list[0];
+  }
+
+  /**
+   * Create a custom audience from customer file
+   * POST /dmp/custom_audience/file/upload/
+   */
+  async createFromFile(params: {
+    advertiser_id: string;
+    audience_name: string;
+    file_paths: string[];
+    calculate_type?: 'DMP_CUSTOMER_FILE_TYPE_PHONE' | 'DMP_CUSTOMER_FILE_TYPE_EMAIL' | 'DMP_CUSTOMER_FILE_TYPE_IDFA' | 'DMP_CUSTOMER_FILE_TYPE_GAID';
+    retention_in_days?: number;
+  }): Promise<{ custom_audience_id: string }> {
+    return this.client.post<{ custom_audience_id: string }>('/dmp/custom_audience/file/upload/', {
+      advertiser_id: params.advertiser_id,
+      custom_audience_name: params.audience_name,
+      file_paths: params.file_paths,
+      calculate_type: params.calculate_type,
+      retention_in_days: params.retention_in_days,
+    });
+  }
+
+  /**
+   * Create a custom audience from rules (engagement, website traffic, etc.)
+   * POST /dmp/custom_audience/rule/create/
+   */
+  async createFromRules(params: {
+    advertiser_id: string;
+    audience_name: string;
+    custom_audience_type: string;
+    retention_in_days?: number;
+    rule?: {
+      inclusions?: Array<{
+        operator: string;
+        rules: Array<{
+          event_source: string;
+          event_type: string;
+          retention_days: number;
+          filter_set?: {
+            filters: Array<{
+              field: string;
+              operator: string;
+              value: string;
+            }>;
+            operator: string;
+          };
+        }>;
+      }>;
+      exclusions?: Array<{
+        operator: string;
+        rules: Array<{
+          event_source: string;
+          event_type: string;
+          retention_days: number;
+        }>;
+      }>;
+    };
+    identity_type?: string;
+    identity_authorized_bc_id?: string;
+  }): Promise<{ custom_audience_id: string }> {
+    return this.client.post<{ custom_audience_id: string }>('/dmp/custom_audience/rule/create/', {
+      advertiser_id: params.advertiser_id,
+      custom_audience_name: params.audience_name,
+      custom_audience_type: params.custom_audience_type,
+      retention_in_days: params.retention_in_days,
+      rule: params.rule,
+      identity_type: params.identity_type,
+      identity_authorized_bc_id: params.identity_authorized_bc_id,
+    });
+  }
+
+  /**
+   * Create a lookalike audience
+   * POST /dmp/custom_audience/lookalike/create/
+   */
+  async createLookalike(params: {
+    advertiser_id: string;
+    audience_name: string;
+    source_audience_id: string;
+    lookalike_spec: LookalikeSpec;
+  }): Promise<{ custom_audience_id: string }> {
+    return this.client.post<{ custom_audience_id: string }>('/dmp/custom_audience/lookalike/create/', {
+      advertiser_id: params.advertiser_id,
+      custom_audience_name: params.audience_name,
+      source_custom_audience_id: params.source_audience_id,
+      lookalike_spec: params.lookalike_spec,
+    });
+  }
+
+  /**
+   * Update a custom audience
+   * POST /dmp/custom_audience/update/
+   */
+  async update(params: AudienceUpdateParams): Promise<{ custom_audience_id: string }> {
+    return this.client.post<{ custom_audience_id: string }>('/dmp/custom_audience/update/', {
+      advertiser_id: params.advertiser_id,
+      custom_audience_id: params.audience_id,
+      custom_audience_name: params.audience_name,
+      action: params.action,
+      file_paths: params.file_paths,
+    });
+  }
+
+  /**
+   * Delete audiences
+   * POST /dmp/custom_audience/delete/
+   */
+  async delete(advertiserId: string, audienceIds: string[]): Promise<{ custom_audience_ids: string[] }> {
+    return this.client.post<{ custom_audience_ids: string[] }>('/dmp/custom_audience/delete/', {
+      advertiser_id: advertiserId,
+      custom_audience_ids: audienceIds,
+    });
+  }
+
+  /**
+   * Share audience to Business Center
+   * POST /dmp/custom_audience/share/
+   */
+  async share(params: {
+    advertiser_id: string;
+    audience_id: string;
+    target_bc_ids: string[];
+  }): Promise<{ custom_audience_id: string }> {
+    return this.client.post<{ custom_audience_id: string }>('/dmp/custom_audience/share/', {
+      advertiser_id: params.advertiser_id,
+      custom_audience_id: params.audience_id,
+      contextual_tag_ids: params.target_bc_ids,
+    });
+  }
+
+  /**
+   * Get audience size estimation
+   * GET /dmp/custom_audience/coverage/
+   */
+  async getCoverage(advertiserId: string, audienceIds: string[]): Promise<{
+    list: Array<{
+      custom_audience_id: string;
+      coverage: number;
+    }>;
+  }> {
+    return this.client.get('/dmp/custom_audience/coverage/', {
+      advertiser_id: advertiserId,
+      custom_audience_ids: audienceIds,
+    });
+  }
+
+  // ============================================
+  // Saved Audiences
+  // ============================================
+
+  /**
+   * List saved audiences
+   * GET /dmp/saved_audience/get/
+   */
+  async listSavedAudiences(
+    advertiserId: string,
+    params?: {
+      filtering?: {
+        saved_audience_ids?: string[];
+      };
+      page?: number;
+      page_size?: number;
+    }
+  ): Promise<PaginatedData<{
+    saved_audience_id: string;
+    saved_audience_name: string;
+    targeting: Record<string, unknown>;
+    create_time: string;
+    modify_time: string;
+  }>> {
+    return this.client.get('/dmp/saved_audience/get/', {
+      advertiser_id: advertiserId,
+      filtering: params?.filtering ? JSON.stringify(params.filtering) : undefined,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Create a saved audience
+   * POST /dmp/saved_audience/create/
+   */
+  async createSavedAudience(params: {
+    advertiser_id: string;
+    saved_audience_name: string;
+    targeting: Record<string, unknown>;
+  }): Promise<{ saved_audience_id: string }> {
+    return this.client.post<{ saved_audience_id: string }>('/dmp/saved_audience/create/', params);
+  }
+
+  /**
+   * Delete saved audiences
+   * POST /dmp/saved_audience/delete/
+   */
+  async deleteSavedAudiences(
+    advertiserId: string,
+    savedAudienceIds: string[]
+  ): Promise<{ saved_audience_ids: string[] }> {
+    return this.client.post<{ saved_audience_ids: string[] }>('/dmp/saved_audience/delete/', {
+      advertiser_id: advertiserId,
+      saved_audience_ids: savedAudienceIds,
+    });
+  }
+}

package/connectors/connect-tiktok/src/api/business.ts

@@ -0,0 +1,273 @@
+import type { TikTokClient } from './client';
+import type { BusinessCenter, BusinessCenterMember, BusinessCenterAsset, BusinessCenterRole, PaginatedData } from '../types';
+
+/**
+ * TikTok Business Center API
+ * Manage Business Center, members, and assets
+ */
+export class BusinessApi {
+  constructor(private readonly client: TikTokClient) {}
+
+  // ============================================
+  // Business Center Management
+  // ============================================
+
+  /**
+   * List Business Centers
+   * GET /bc/get/
+   */
+  async list(params?: {
+    filtering?: {
+      bc_ids?: string[];
+    };
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<BusinessCenter>> {
+    return this.client.get<PaginatedData<BusinessCenter>>('/bc/get/', {
+      filtering: params?.filtering ? JSON.stringify(params.filtering) : undefined,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Get Business Center by ID
+   */
+  async get(bcId: string): Promise<BusinessCenter> {
+    const response = await this.list({
+      filtering: { bc_ids: [bcId] },
+    });
+    if (!response.list || response.list.length === 0) {
+      throw new Error(`Business Center ${bcId} not found`);
+    }
+    return response.list[0];
+  }
+
+  // ============================================
+  // Member Management
+  // ============================================
+
+  /**
+   * List Business Center members
+   * GET /bc/member/get/
+   */
+  async listMembers(bcId: string, params?: {
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<BusinessCenterMember>> {
+    return this.client.get<PaginatedData<BusinessCenterMember>>('/bc/member/get/', {
+      bc_id: bcId,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Invite a member to Business Center
+   * POST /bc/member/invite/
+   */
+  async inviteMember(params: {
+    bc_id: string;
+    email: string;
+    role: BusinessCenterRole;
+  }): Promise<{ invitation_id: string }> {
+    return this.client.post<{ invitation_id: string }>('/bc/member/invite/', params);
+  }
+
+  /**
+   * Update member role
+   * POST /bc/member/update/
+   */
+  async updateMemberRole(params: {
+    bc_id: string;
+    user_id: string;
+    role: BusinessCenterRole;
+  }): Promise<{ bc_id: string; user_id: string }> {
+    return this.client.post('/bc/member/update/', params);
+  }
+
+  /**
+   * Remove member from Business Center
+   * POST /bc/member/remove/
+   */
+  async removeMember(bcId: string, userId: string): Promise<{ bc_id: string; user_id: string }> {
+    return this.client.post('/bc/member/remove/', {
+      bc_id: bcId,
+      user_id: userId,
+    });
+  }
+
+  // ============================================
+  // Asset Management
+  // ============================================
+
+  /**
+   * List Business Center assets
+   * GET /bc/asset/get/
+   */
+  async listAssets(bcId: string, params?: {
+    asset_type?: 'ADVERTISER' | 'CATALOG' | 'PIXEL' | 'TIKTOK_ACCOUNT';
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<BusinessCenterAsset>> {
+    return this.client.get<PaginatedData<BusinessCenterAsset>>('/bc/asset/get/', {
+      bc_id: bcId,
+      asset_type: params?.asset_type,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Add an advertiser asset to Business Center
+   * POST /bc/advertiser/add/
+   */
+  async addAdvertiser(params: {
+    bc_id: string;
+    advertiser_ids: string[];
+  }): Promise<{ bc_id: string; advertiser_ids: string[] }> {
+    return this.client.post('/bc/advertiser/add/', params);
+  }
+
+  /**
+   * Create an advertiser under Business Center
+   * POST /bc/advertiser/create/
+   */
+  async createAdvertiser(params: {
+    bc_id: string;
+    advertiser_name: string;
+    timezone?: string;
+    currency?: string;
+    company?: string;
+    industry?: string;
+  }): Promise<{ advertiser_id: string }> {
+    return this.client.post<{ advertiser_id: string }>('/bc/advertiser/create/', params);
+  }
+
+  /**
+   * Get advertisers under Business Center
+   * GET /bc/advertiser/get/
+   */
+  async listAdvertisers(bcId: string, params?: {
+    filtering?: {
+      advertiser_ids?: string[];
+    };
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<{
+    advertiser_id: string;
+    advertiser_name: string;
+    status: string;
+    create_time: string;
+  }>> {
+    return this.client.get('/bc/advertiser/get/', {
+      bc_id: bcId,
+      filtering: params?.filtering ? JSON.stringify(params.filtering) : undefined,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  // ============================================
+  // Partner Management
+  // ============================================
+
+  /**
+   * List Business Center partners
+   * GET /bc/partner/get/
+   */
+  async listPartners(bcId: string, params?: {
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<{
+    partner_bc_id: string;
+    partner_bc_name: string;
+    partnership_type: string;
+    status: string;
+    create_time: string;
+  }>> {
+    return this.client.get('/bc/partner/get/', {
+      bc_id: bcId,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Invite a partner Business Center
+   * POST /bc/partner/invite/
+   */
+  async invitePartner(params: {
+    bc_id: string;
+    partner_bc_id: string;
+    partnership_type: 'AGENCY' | 'ADVERTISER';
+  }): Promise<{ invitation_id: string }> {
+    return this.client.post<{ invitation_id: string }>('/bc/partner/invite/', params);
+  }
+
+  // ============================================
+  // Fund Management
+  // ============================================
+
+  /**
+   * Get Business Center balance
+   * GET /bc/balance/get/
+   */
+  async getBalance(bcId: string): Promise<{
+    balance: number;
+    cash: number;
+    grant: number;
+    currency: string;
+  }> {
+    return this.client.get('/bc/balance/get/', {
+      bc_id: bcId,
+    });
+  }
+
+  /**
+   * Transfer funds between BC and advertiser
+   * POST /bc/transfer/
+   */
+  async transfer(params: {
+    bc_id: string;
+    advertiser_id: string;
+    transfer_type: 'BC_TO_ADVERTISER' | 'ADVERTISER_TO_BC';
+    amount: number;
+  }): Promise<{
+    transfer_id: string;
+    bc_id: string;
+    advertiser_id: string;
+    amount: number;
+  }> {
+    return this.client.post('/bc/transfer/', params);
+  }
+
+  /**
+   * Get fund transfer history
+   * GET /bc/transfer/get/
+   */
+  async getTransferHistory(bcId: string, params?: {
+    advertiser_id?: string;
+    start_date?: string;
+    end_date?: string;
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<{
+    transfer_id: string;
+    bc_id: string;
+    advertiser_id: string;
+    transfer_type: string;
+    amount: number;
+    currency: string;
+    create_time: string;
+  }>> {
+    return this.client.get('/bc/transfer/get/', {
+      bc_id: bcId,
+      advertiser_id: params?.advertiser_id,
+      start_date: params?.start_date,
+      end_date: params?.end_date,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+}

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

@@ -0,0 +1,116 @@
+import type { TikTokClient } from './client';
+import type {
+  Campaign,
+  CampaignCreateParams,
+  CampaignUpdateParams,
+  CampaignListParams,
+  PaginatedData,
+  OperationStatus,
+} from '../types';
+
+/**
+ * TikTok Campaigns API
+ * Create, read, update, and delete campaigns
+ */
+export class CampaignsApi {
+  constructor(private readonly client: TikTokClient) {}
+
+  /**
+   * List campaigns
+   * GET /campaign/get/
+   */
+  async list(params: CampaignListParams): Promise<PaginatedData<Campaign>> {
+    return this.client.get<PaginatedData<Campaign>>('/campaign/get/', {
+      advertiser_id: params.advertiser_id,
+      filtering: params.filtering ? JSON.stringify(params.filtering) : undefined,
+      page: params.page,
+      page_size: params.page_size,
+      fields: params.fields,
+    });
+  }
+
+  /**
+   * Get a single campaign by ID
+   */
+  async get(advertiserId: string, campaignId: string): Promise<Campaign> {
+    const response = await this.list({
+      advertiser_id: advertiserId,
+      filtering: { campaign_ids: [campaignId] },
+    });
+    if (!response.list || response.list.length === 0) {
+      throw new Error(`Campaign ${campaignId} not found`);
+    }
+    return response.list[0];
+  }
+
+  /**
+   * Create a new campaign
+   * POST /campaign/create/
+   */
+  async create(params: CampaignCreateParams): Promise<{ campaign_id: string }> {
+    return this.client.post<{ campaign_id: string }>('/campaign/create/', params);
+  }
+
+  /**
+   * Update an existing campaign
+   * POST /campaign/update/
+   */
+  async update(params: CampaignUpdateParams): Promise<{ campaign_id: string }> {
+    return this.client.post<{ campaign_id: string }>('/campaign/update/', params);
+  }
+
+  /**
+   * Delete campaigns
+   * POST /campaign/delete/
+   */
+  async delete(advertiserId: string, campaignIds: string[]): Promise<{ campaign_ids: string[] }> {
+    return this.client.post<{ campaign_ids: string[] }>('/campaign/delete/', {
+      advertiser_id: advertiserId,
+      campaign_ids: campaignIds,
+    });
+  }
+
+  /**
+   * Update campaign status (enable/disable)
+   * POST /campaign/status/update/
+   */
+  async updateStatus(
+    advertiserId: string,
+    campaignIds: string[],
+    operationStatus: OperationStatus
+  ): Promise<{ campaign_ids: string[] }> {
+    return this.client.post<{ campaign_ids: string[] }>('/campaign/status/update/', {
+      advertiser_id: advertiserId,
+      campaign_ids: campaignIds,
+      operation_status: operationStatus,
+    });
+  }
+
+  /**
+   * Enable campaigns
+   */
+  async enable(advertiserId: string, campaignIds: string[]): Promise<{ campaign_ids: string[] }> {
+    return this.updateStatus(advertiserId, campaignIds, 'ENABLE');
+  }
+
+  /**
+   * Disable campaigns
+   */
+  async disable(advertiserId: string, campaignIds: string[]): Promise<{ campaign_ids: string[] }> {
+    return this.updateStatus(advertiserId, campaignIds, 'DISABLE');
+  }
+
+  /**
+   * Create GMV Max Campaign
+   * POST /campaign/create/ with campaign_type: GMV_MAX_CAMPAIGN
+   */
+  async createGmvMax(params: Omit<CampaignCreateParams, 'campaign_type'> & {
+    shop_id: string;
+    store_authorized_bc_id?: string;
+  }): Promise<{ campaign_id: string }> {
+    return this.client.post<{ campaign_id: string }>('/campaign/create/', {
+      ...params,
+      campaign_type: 'GMV_MAX_CAMPAIGN',
+    });
+  }
+}