@hasna/connectors 0.0.1

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

@@ -0,0 +1,326 @@
+import type { TikTokClient } from './client';
+import type { Catalog, CatalogCreateParams, ProductSet, Product, PaginatedData } from '../types';
+
+/**
+ * TikTok Catalogs API
+ * Manage product catalogs and feeds for shopping ads
+ */
+export class CatalogsApi {
+  constructor(private readonly client: TikTokClient) {}
+
+  // ============================================
+  // Catalog Management
+  // ============================================
+
+  /**
+   * List catalogs
+   * GET /catalog/get/
+   */
+  async list(bcId: string, params?: {
+    filtering?: {
+      catalog_ids?: string[];
+    };
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<Catalog>> {
+    return this.client.get<PaginatedData<Catalog>>('/catalog/get/', {
+      bc_id: bcId,
+      filtering: params?.filtering ? JSON.stringify(params.filtering) : undefined,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Get a single catalog by ID
+   */
+  async get(bcId: string, catalogId: string): Promise<Catalog> {
+    const response = await this.list(bcId, {
+      filtering: { catalog_ids: [catalogId] },
+    });
+    if (!response.list || response.list.length === 0) {
+      throw new Error(`Catalog ${catalogId} not found`);
+    }
+    return response.list[0];
+  }
+
+  /**
+   * Create a catalog
+   * POST /catalog/create/
+   */
+  async create(params: CatalogCreateParams): Promise<{ catalog_id: string }> {
+    return this.client.post<{ catalog_id: string }>('/catalog/create/', params);
+  }
+
+  /**
+   * Update a catalog
+   * POST /catalog/update/
+   */
+  async update(params: {
+    bc_id: string;
+    catalog_id: string;
+    catalog_name?: string;
+  }): Promise<{ catalog_id: string }> {
+    return this.client.post<{ catalog_id: string }>('/catalog/update/', params);
+  }
+
+  /**
+   * Delete a catalog
+   * POST /catalog/delete/
+   */
+  async delete(bcId: string, catalogId: string): Promise<{ catalog_id: string }> {
+    return this.client.post<{ catalog_id: string }>('/catalog/delete/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+    });
+  }
+
+  // ============================================
+  // Product Sets
+  // ============================================
+
+  /**
+   * List product sets
+   * GET /catalog/product_set/get/
+   */
+  async listProductSets(bcId: string, catalogId: string, params?: {
+    filtering?: {
+      product_set_ids?: string[];
+    };
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<ProductSet>> {
+    return this.client.get<PaginatedData<ProductSet>>('/catalog/product_set/get/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+      filtering: params?.filtering ? JSON.stringify(params.filtering) : undefined,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Create a product set
+   * POST /catalog/product_set/create/
+   */
+  async createProductSet(params: {
+    bc_id: string;
+    catalog_id: string;
+    product_set_name: string;
+    filter?: {
+      field: string;
+      operator: string;
+      value: string | string[];
+    }[];
+  }): Promise<{ product_set_id: string }> {
+    return this.client.post<{ product_set_id: string }>('/catalog/product_set/create/', params);
+  }
+
+  /**
+   * Update a product set
+   * POST /catalog/product_set/update/
+   */
+  async updateProductSet(params: {
+    bc_id: string;
+    catalog_id: string;
+    product_set_id: string;
+    product_set_name?: string;
+    filter?: {
+      field: string;
+      operator: string;
+      value: string | string[];
+    }[];
+  }): Promise<{ product_set_id: string }> {
+    return this.client.post<{ product_set_id: string }>('/catalog/product_set/update/', params);
+  }
+
+  /**
+   * Delete a product set
+   * POST /catalog/product_set/delete/
+   */
+  async deleteProductSet(bcId: string, catalogId: string, productSetId: string): Promise<{ product_set_id: string }> {
+    return this.client.post<{ product_set_id: string }>('/catalog/product_set/delete/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+      product_set_id: productSetId,
+    });
+  }
+
+  // ============================================
+  // Products
+  // ============================================
+
+  /**
+   * List products
+   * GET /catalog/product/get/
+   */
+  async listProducts(bcId: string, catalogId: string, params?: {
+    filtering?: {
+      sku_ids?: string[];
+      item_group_ids?: string[];
+      availability?: string;
+    };
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<Product>> {
+    return this.client.get<PaginatedData<Product>>('/catalog/product/get/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+      filtering: params?.filtering ? JSON.stringify(params.filtering) : undefined,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Create/update products
+   * POST /catalog/product/upload/
+   */
+  async uploadProducts(params: {
+    bc_id: string;
+    catalog_id: string;
+    products: Array<{
+      sku_id: string;
+      title: string;
+      description?: string;
+      availability: string;
+      price: number;
+      sale_price?: number;
+      currency: string;
+      image_link: string;
+      link: string;
+      brand?: string;
+      item_group_id?: string;
+      additional_image_link?: string[];
+    }>;
+  }): Promise<{
+    success_count: number;
+    failed_count: number;
+    failed_products?: Array<{
+      sku_id: string;
+      error_message: string;
+    }>;
+  }> {
+    return this.client.post('/catalog/product/upload/', params);
+  }
+
+  /**
+   * Delete products
+   * POST /catalog/product/delete/
+   */
+  async deleteProducts(bcId: string, catalogId: string, skuIds: string[]): Promise<{
+    deleted_count: number;
+    failed_count: number;
+  }> {
+    return this.client.post('/catalog/product/delete/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+      sku_ids: skuIds,
+    });
+  }
+
+  // ============================================
+  // Feeds
+  // ============================================
+
+  /**
+   * List feeds
+   * GET /catalog/feed/get/
+   */
+  async listFeeds(bcId: string, catalogId: string, params?: {
+    page?: number;
+    page_size?: number;
+  }): Promise<PaginatedData<{
+    feed_id: string;
+    feed_name: string;
+    feed_type: string;
+    status: string;
+    product_count: number;
+    last_fetch_time?: string;
+    create_time: string;
+  }>> {
+    return this.client.get('/catalog/feed/get/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+      page: params?.page,
+      page_size: params?.page_size,
+    });
+  }
+
+  /**
+   * Create a feed
+   * POST /catalog/feed/create/
+   */
+  async createFeed(params: {
+    bc_id: string;
+    catalog_id: string;
+    feed_name: string;
+    feed_type: 'URL' | 'FILE' | 'API';
+    fetch_url?: string;
+    schedule_type?: 'DAILY' | 'HOURLY' | 'WEEKLY';
+    schedule_hour?: number;
+    file_name?: string;
+    file_url?: string;
+  }): Promise<{ feed_id: string }> {
+    return this.client.post<{ feed_id: string }>('/catalog/feed/create/', params);
+  }
+
+  /**
+   * Update a feed
+   * POST /catalog/feed/update/
+   */
+  async updateFeed(params: {
+    bc_id: string;
+    catalog_id: string;
+    feed_id: string;
+    feed_name?: string;
+    fetch_url?: string;
+    schedule_type?: 'DAILY' | 'HOURLY' | 'WEEKLY';
+    schedule_hour?: number;
+  }): Promise<{ feed_id: string }> {
+    return this.client.post<{ feed_id: string }>('/catalog/feed/update/', params);
+  }
+
+  /**
+   * Delete a feed
+   * POST /catalog/feed/delete/
+   */
+  async deleteFeed(bcId: string, catalogId: string, feedId: string): Promise<{ feed_id: string }> {
+    return this.client.post<{ feed_id: string }>('/catalog/feed/delete/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+      feed_id: feedId,
+    });
+  }
+
+  /**
+   * Trigger feed fetch
+   * POST /catalog/feed/fetch/
+   */
+  async fetchFeed(bcId: string, catalogId: string, feedId: string): Promise<{ task_id: string }> {
+    return this.client.post<{ task_id: string }>('/catalog/feed/fetch/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+      feed_id: feedId,
+    });
+  }
+
+  /**
+   * Get feed fetch status
+   * GET /catalog/feed/fetch/status/
+   */
+  async getFetchStatus(bcId: string, catalogId: string, feedId: string, taskId: string): Promise<{
+    task_id: string;
+    status: 'QUEUING' | 'PROCESSING' | 'SUCCESS' | 'FAILED';
+    products_uploaded?: number;
+    products_failed?: number;
+    error_message?: string;
+  }> {
+    return this.client.get('/catalog/feed/fetch/status/', {
+      bc_id: bcId,
+      catalog_id: catalogId,
+      feed_id: feedId,
+      task_id: taskId,
+    });
+  }
+}

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

@@ -0,0 +1,137 @@
+import type { TikTokConfig, TikTokApiResponse } from '../types';
+import { TikTokApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://business-api.tiktok.com/open_api/v1.3';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | string[] | undefined>;
+  body?: Record<string, unknown> | unknown[] | string | object;
+  headers?: Record<string, string>;
+}
+
+export class TikTokClient {
+  private readonly accessToken: string;
+  private readonly baseUrl: string;
+  private readonly defaultAdvertiserId?: string;
+
+  constructor(config: TikTokConfig) {
+    if (!config.accessToken) {
+      throw new Error('Access token is required');
+    }
+    this.accessToken = config.accessToken;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+    this.defaultAdvertiserId = config.advertiserId;
+  }
+
+  getDefaultAdvertiserId(): string | undefined {
+    return this.defaultAdvertiserId;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | string[] | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          if (Array.isArray(value)) {
+            // TikTok API expects arrays as JSON strings
+            url.searchParams.append(key, JSON.stringify(value));
+          } else {
+            url.searchParams.append(key, String(value));
+          }
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make an authenticated request to TikTok Marketing API
+   * TikTok uses Bearer token authentication
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      'Access-Token': this.accessToken,
+      'Accept': 'application/json',
+      ...headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Parse response
+    let data: TikTokApiResponse<T>;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          throw new TikTokApiError(`Invalid JSON response: ${text}`, response.status, 'unknown');
+        }
+      } else {
+        throw new TikTokApiError('Empty response body', response.status, 'unknown');
+      }
+    } else {
+      const text = await response.text();
+      throw new TikTokApiError(`Unexpected content type: ${contentType}. Body: ${text}`, response.status, 'unknown');
+    }
+
+    // Handle TikTok API errors (they return 200 with error codes in body)
+    if (data.code !== 0) {
+      throw new TikTokApiError(data.message, data.code, data.request_id);
+    }
+
+    return data.data;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | string[] | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object, params?: Record<string, string | number | boolean | string[] | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | string[] | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body, params });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | string[] | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | string[] | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  /**
+   * Get a preview of the access token (for display/debugging)
+   */
+  getAccessTokenPreview(): string {
+    if (this.accessToken.length > 10) {
+      return `${this.accessToken.substring(0, 6)}...${this.accessToken.substring(this.accessToken.length - 4)}`;
+    }
+    return '***';
+  }
+}