@hasna/connectors 0.8.1 → 0.9.0

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

@@ -0,0 +1,392 @@
+import { ClickBankClient } from './client';
+import type {
+  Role,
+  SubscriptionTrend,
+  SubscriptionDetails,
+  AnalyticsStats,
+  AnalyticsStatus,
+  SubscriptionTrendsParams,
+  SubscriptionDetailsParams,
+  AnalyticsStatsParams,
+  SubscriptionDetailFilter,
+  SubscriptionDetailFilterParams,
+  AnalyticsSummaryParams,
+} from '../types';
+
+interface SubscriptionTrendsResponse {
+  subscriptionTrend?: SubscriptionTrend[];
+}
+
+interface SubscriptionDetailsResponse {
+  subscriptionDetails?: SubscriptionDetails[];
+  _hasMore?: boolean;
+}
+
+interface AnalyticsStatsResponse {
+  analyticsData?: AnalyticsStats[];
+}
+
+export class AnalyticsApi {
+  constructor(private readonly client: ClickBankClient) {}
+
+  /**
+   * Get API status and last update time
+   */
+  async getStatus(): Promise<AnalyticsStatus> {
+    return this.client.get<AnalyticsStatus>('/analytics/status');
+  }
+
+  /**
+   * Get subscription trends for a date range
+   * Note: Only available for vendor role
+   */
+  async getSubscriptionTrends(params: SubscriptionTrendsParams): Promise<SubscriptionTrend[]> {
+    const { role, ...queryParams } = params;
+    const response = await this.client.get<SubscriptionTrendsResponse>(
+      `/analytics/${role.toLowerCase()}/subscription/trends`,
+      queryParams as Record<string, string | number | boolean | undefined>
+    );
+    return response.subscriptionTrend || [];
+  }
+
+  /**
+   * Get subscription details
+   * Note: Only available for vendor role
+   */
+  async getSubscriptionDetails(
+    params: SubscriptionDetailsParams
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    const { role, page, ...queryParams } = params;
+    const headers = page ? { page: String(page) } : undefined;
+
+    const response = await this.client.request<SubscriptionDetailsResponse>(
+      `/analytics/${role.toLowerCase()}/subscription/details`,
+      {
+        method: 'GET',
+        params: queryParams as Record<string, string | number | boolean | undefined>,
+        headers,
+      }
+    );
+
+    return {
+      details: response.subscriptionDetails || [],
+      hasMore: !!response._hasMore,
+    };
+  }
+
+  /**
+   * Get subscription status summary
+   * Note: Only available for vendor role
+   */
+  async getSubscriptionStatus(
+    role: Role,
+    account?: string
+  ): Promise<Record<string, number>> {
+    return this.client.get<Record<string, number>>(
+      `/analytics/${role.toLowerCase()}/subscription/status`,
+      account ? { account } : undefined
+    );
+  }
+
+  /**
+   * Get summary statistics by dimension
+   */
+  async getStats(params: AnalyticsStatsParams): Promise<AnalyticsStats[]> {
+    const { role, dimension, ...queryParams } = params;
+    const response = await this.client.get<AnalyticsStatsResponse>(
+      `/analytics/${role.toLowerCase()}/${dimension.toLowerCase()}`,
+      queryParams as Record<string, string | number | boolean | undefined>
+    );
+    return response.analyticsData || [];
+  }
+
+  /**
+   * Get vendor stats by product SKU
+   */
+  async getVendorProductStats(
+    account?: string,
+    startDate?: string,
+    endDate?: string
+  ): Promise<AnalyticsStats[]> {
+    return this.getStats({
+      role: 'VENDOR',
+      dimension: 'PRODUCT_SKU',
+      account,
+      startDate,
+      endDate,
+    });
+  }
+
+  /**
+   * Get affiliate stats by vendor product SKU
+   */
+  async getAffiliateVendorStats(
+    account?: string,
+    startDate?: string,
+    endDate?: string
+  ): Promise<AnalyticsStats[]> {
+    return this.getStats({
+      role: 'AFFILIATE',
+      dimension: 'VENDOR_PRODUCT_SKU',
+      account,
+      startDate,
+      endDate,
+    });
+  }
+
+  /**
+   * Get stats by country
+   */
+  async getCountryStats(
+    role: Role,
+    account?: string,
+    startDate?: string,
+    endDate?: string
+  ): Promise<AnalyticsStats[]> {
+    return this.getStats({
+      role,
+      dimension: 'COUNTRY',
+      account,
+      startDate,
+      endDate,
+    });
+  }
+
+  /**
+   * Get all subscription details (handles pagination)
+   * Note: Only available for vendor role
+   */
+  async getAllSubscriptionDetails(
+    account?: string,
+    status?: string
+  ): Promise<SubscriptionDetails[]> {
+    const result: SubscriptionDetails[] = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await this.getSubscriptionDetails({
+        role: 'VENDOR',
+        account,
+        status,
+        page,
+      });
+
+      result.push(...response.details);
+      hasMore = response.hasMore;
+      page++;
+    }
+
+    return result;
+  }
+
+  /**
+   * Get subscription details with a specific filter
+   * Available filters: canceldate, cancelsixty, cancelthirty, compsixty, compthirty, nextpmtdate, startdate, status
+   */
+  async getSubscriptionDetailsByFilter(
+    filter: SubscriptionDetailFilter,
+    params: SubscriptionDetailFilterParams
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    const { role, page, ...queryParams } = params;
+    const headers = page ? { page: String(page) } : undefined;
+
+    const response = await this.client.request<SubscriptionDetailsResponse>(
+      `/analytics/${role.toLowerCase()}/subscription/details/${filter}`,
+      {
+        method: 'GET',
+        params: queryParams as Record<string, string | number | boolean | undefined>,
+        headers,
+      }
+    );
+
+    return {
+      details: response.subscriptionDetails || [],
+      hasMore: !!response._hasMore,
+    };
+  }
+
+  /**
+   * Get subscriptions canceled within a date range
+   */
+  async getCanceledByDateRange(
+    account: string,
+    startDate: string,
+    endDate: string,
+    page?: number
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    return this.getSubscriptionDetailsByFilter('canceldate', {
+      role: 'VENDOR',
+      account,
+      startDate,
+      endDate,
+      page,
+    });
+  }
+
+  /**
+   * Get subscriptions canceled in the last 60 days
+   */
+  async getCanceledLast60Days(
+    account: string,
+    page?: number
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    return this.getSubscriptionDetailsByFilter('cancelsixty', {
+      role: 'VENDOR',
+      account,
+      page,
+    });
+  }
+
+  /**
+   * Get subscriptions canceled in the last 30 days
+   */
+  async getCanceledLast30Days(
+    account: string,
+    page?: number
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    return this.getSubscriptionDetailsByFilter('cancelthirty', {
+      role: 'VENDOR',
+      account,
+      page,
+    });
+  }
+
+  /**
+   * Get subscriptions completing within 60 days
+   */
+  async getCompletingIn60Days(
+    account: string,
+    page?: number
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    return this.getSubscriptionDetailsByFilter('compsixty', {
+      role: 'VENDOR',
+      account,
+      page,
+    });
+  }
+
+  /**
+   * Get subscriptions completing within 30 days
+   */
+  async getCompletingIn30Days(
+    account: string,
+    page?: number
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    return this.getSubscriptionDetailsByFilter('compthirty', {
+      role: 'VENDOR',
+      account,
+      page,
+    });
+  }
+
+  /**
+   * Get subscriptions with next payment date in a date range
+   */
+  async getByNextPaymentDate(
+    account: string,
+    startDate: string,
+    endDate: string,
+    page?: number
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    return this.getSubscriptionDetailsByFilter('nextpmtdate', {
+      role: 'VENDOR',
+      account,
+      startDate,
+      endDate,
+      page,
+    });
+  }
+
+  /**
+   * Get subscriptions with start date in a date range
+   */
+  async getByStartDate(
+    account: string,
+    startDate: string,
+    endDate: string,
+    page?: number
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    return this.getSubscriptionDetailsByFilter('startdate', {
+      role: 'VENDOR',
+      account,
+      startDate,
+      endDate,
+      page,
+    });
+  }
+
+  /**
+   * Get subscriptions by status
+   * Status can be: ACTIVE, COMPLETED, CANCELED, RETRY_PAYMENT, REQUEST_NEW_CARD
+   */
+  async getBySubscriptionStatus(
+    account: string,
+    status: 'ACTIVE' | 'COMPLETED' | 'CANCELED' | 'RETRY_PAYMENT' | 'REQUEST_NEW_CARD',
+    page?: number
+  ): Promise<{ details: SubscriptionDetails[]; hasMore: boolean }> {
+    return this.getSubscriptionDetailsByFilter('status', {
+      role: 'VENDOR',
+      account,
+      status,
+      page,
+    });
+  }
+
+  /**
+   * Get summary statistics by dimension
+   */
+  async getStatsSummary(params: AnalyticsSummaryParams): Promise<AnalyticsStats[]> {
+    const { role, dimension, ...queryParams } = params;
+    const response = await this.client.get<AnalyticsStatsResponse>(
+      `/analytics/${role.toLowerCase()}/${dimension.toLowerCase()}/summary`,
+      queryParams as Record<string, string | number | boolean | undefined>
+    );
+    return response.analyticsData || [];
+  }
+
+  /**
+   * Get vendor summary stats by product SKU
+   */
+  async getVendorProductSummary(
+    account?: string,
+    startDate?: string,
+    endDate?: string
+  ): Promise<AnalyticsStats[]> {
+    return this.getStatsSummary({
+      role: 'VENDOR',
+      dimension: 'PRODUCT_SKU',
+      account,
+      startDate,
+      endDate,
+    });
+  }
+
+  /**
+   * Get all analytics schemas
+   */
+  async getSchemas(): Promise<{
+    analyticsResult: string;
+    analyticsStatus: string;
+    subscriptionDetail: string;
+    subscriptionTrends: string;
+    subscriptionDetailRow: string;
+  }> {
+    const [analyticsResult, analyticsStatus, subscriptionDetail, subscriptionTrends, subscriptionDetailRow] =
+      await Promise.all([
+        this.client.get<string>('/analytics/schema/AnalyticsResult', undefined, 'xml'),
+        this.client.get<string>('/analytics/schema/AnalyticsStatus', undefined, 'xml'),
+        this.client.get<string>('/analytics/schema/SubscriptionDetailResult', undefined, 'xml'),
+        this.client.get<string>('/analytics/schema/SubscriptionTrendsData', undefined, 'xml'),
+        this.client.get<string>('/analytics/schema/SubscriptionDetailResultRow', undefined, 'xml'),
+      ]);
+
+    return {
+      analyticsResult,
+      analyticsStatus,
+      subscriptionDetail,
+      subscriptionTrends,
+      subscriptionDetailRow,
+    };
+  }
+}

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

@@ -0,0 +1,153 @@
+import type { ClickBankConfig, OutputFormat } from '../types';
+import { ClickBankApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://api.clickbank.com/rest/1.3';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  format?: OutputFormat;
+}
+
+export class ClickBankClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: ClickBankConfig) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  private getAcceptHeader(format: OutputFormat = 'json'): string {
+    return format === 'xml' ? 'application/xml' : 'application/json';
+  }
+
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {}, format = 'json' } = options;
+
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      'Authorization': this.apiKey,
+      'Accept': this.getAcceptHeader(format),
+      ...headers,
+    };
+
+    if (body && (method === 'POST' || method === 'PUT')) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && (method === 'POST' || method === 'PUT')) {
+      fetchOptions.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle HEAD requests (status check)
+    if (method === 'HEAD') {
+      return {
+        active: response.status === 204,
+        statusCode: response.status
+      } as T;
+    }
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Handle partial content (pagination)
+    const hasMore = response.status === 206;
+
+    // Parse response
+    let data: unknown;
+    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 {
+          data = text;
+        }
+      }
+    } else if (contentType.includes('application/xml')) {
+      data = await response.text();
+    } else {
+      const text = await response.text();
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+
+    // Handle errors
+    if (!response.ok && response.status !== 206) {
+      const errorMessage = typeof data === 'object' && data !== null
+        ? JSON.stringify(data)
+        : String(data || response.statusText);
+      throw new ClickBankApiError(errorMessage, response.status);
+    }
+
+    // Add pagination info if needed
+    if (hasMore && typeof data === 'object' && data !== null) {
+      (data as Record<string, unknown>)._hasMore = true;
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, format?: OutputFormat): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params, format });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown>, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown>, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  async head<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'HEAD', params });
+  }
+
+  // Utility to get API key (for display/debugging)
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}

package/connectors/connect-clickbank/src/api/images.ts

@@ -0,0 +1,90 @@
+import { ClickBankClient } from './client';
+import type { ImageData, ImagesListParams, ImageType } from '../types';
+
+interface ImagesResponse {
+  imageData?: ImageData[];
+  _hasMore?: boolean;
+}
+
+export class ImagesApi {
+  constructor(private readonly client: ClickBankClient) {}
+
+  /**
+   * Get the XML schema for image data results
+   */
+  async getSchema(): Promise<string> {
+    return this.client.get<string>('/images/schema', undefined, 'xml');
+  }
+
+  /**
+   * List images associated with an account
+   */
+  async list(params: ImagesListParams): Promise<{ images: ImageData[]; hasMore: boolean }> {
+    const { page, ...queryParams } = params;
+    const headers = page ? { page: String(page) } : undefined;
+
+    const response = await this.client.request<ImagesResponse>('/images/list', {
+      method: 'GET',
+      params: queryParams as Record<string, string | number | boolean | undefined>,
+      headers,
+    });
+
+    return {
+      images: response.imageData || [],
+      hasMore: !!response._hasMore,
+    };
+  }
+
+  /**
+   * Get all images for an account (handles pagination)
+   */
+  async getAll(site: string, approvedOnly?: boolean, type?: ImageType): Promise<ImageData[]> {
+    const result: ImageData[] = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await this.list({ site, approvedOnly, type, page });
+      result.push(...response.images);
+      hasMore = response.hasMore;
+      page++;
+    }
+
+    return result;
+  }
+
+  /**
+   * Get only approved images for an account
+   */
+  async getApproved(site: string, type?: ImageType): Promise<{ images: ImageData[]; hasMore: boolean }> {
+    return this.list({ site, approvedOnly: true, type });
+  }
+
+  /**
+   * Get product images for an account
+   */
+  async getProductImages(site: string, approvedOnly?: boolean): Promise<{ images: ImageData[]; hasMore: boolean }> {
+    return this.list({ site, approvedOnly, type: 'PRODUCT' });
+  }
+
+  /**
+   * Get banner images for an account
+   */
+  async getBannerImages(site: string, approvedOnly?: boolean): Promise<{ images: ImageData[]; hasMore: boolean }> {
+    return this.list({ site, approvedOnly, type: 'BANNER' });
+  }
+
+  /**
+   * Get custom banner images for an account
+   */
+  async getCustomBannerImages(site: string, approvedOnly?: boolean): Promise<{ images: ImageData[]; hasMore: boolean }> {
+    return this.list({ site, approvedOnly, type: 'CUSTOM_BANNER' });
+  }
+
+  /**
+   * Get custom orderform images for an account
+   */
+  async getOrderformImages(site: string, approvedOnly?: boolean): Promise<{ images: ImageData[]; hasMore: boolean }> {
+    return this.list({ site, approvedOnly, type: 'CUSTOM_ORDERFORM' });
+  }
+}

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

@@ -0,0 +1,61 @@
+import type { ClickBankConfig } from '../types';
+import { ClickBankClient } from './client';
+import { OrdersApi } from './orders';
+import { ProductsApi } from './products';
+import { TicketsApi } from './tickets';
+import { ShippingApi } from './shipping';
+import { QuickstatsApi } from './quickstats';
+import { AnalyticsApi } from './analytics';
+import { ImagesApi } from './images';
+
+export class ClickBank {
+  private readonly client: ClickBankClient;
+
+  public readonly orders: OrdersApi;
+  public readonly products: ProductsApi;
+  public readonly tickets: TicketsApi;
+  public readonly shipping: ShippingApi;
+  public readonly quickstats: QuickstatsApi;
+  public readonly analytics: AnalyticsApi;
+  public readonly images: ImagesApi;
+
+  constructor(config: ClickBankConfig) {
+    this.client = new ClickBankClient(config);
+
+    this.orders = new OrdersApi(this.client);
+    this.products = new ProductsApi(this.client);
+    this.tickets = new TicketsApi(this.client);
+    this.shipping = new ShippingApi(this.client);
+    this.quickstats = new QuickstatsApi(this.client);
+    this.analytics = new AnalyticsApi(this.client);
+    this.images = new ImagesApi(this.client);
+  }
+
+  /**
+   * Create a ClickBank client from environment variables
+   * Looks for CLICKBANK_API_KEY
+   */
+  static fromEnv(): ClickBank {
+    const apiKey = process.env.CLICKBANK_API_KEY;
+    if (!apiKey) {
+      throw new Error('CLICKBANK_API_KEY environment variable is required');
+    }
+    return new ClickBank({ apiKey });
+  }
+
+  /**
+   * Get a preview of the API key (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+}
+
+export { ClickBankClient } from './client';
+export { OrdersApi } from './orders';
+export { ProductsApi } from './products';
+export { TicketsApi } from './tickets';
+export { ShippingApi } from './shipping';
+export { QuickstatsApi } from './quickstats';
+export { AnalyticsApi } from './analytics';
+export { ImagesApi } from './images';