@hasna/connectors 0.8.1 → 0.9.0

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

@@ -0,0 +1,135 @@
+import { ClickBankClient } from './client';
+import type {
+  OrderData,
+  OrdersListParams,
+  ChangeProductParams,
+  ChangeAddressParams,
+  ChangeDateParams,
+  ExtendParams,
+  PauseParams,
+  ReinstateParams,
+} from '../types';
+
+interface OrderDataResponse {
+  orderData?: OrderData | OrderData[];
+}
+
+interface OrderListResponse {
+  orderData?: OrderData[];
+  _hasMore?: boolean;
+}
+
+export class OrdersApi {
+  constructor(private readonly client: ClickBankClient) {}
+
+  /**
+   * Get the XML schema for order data results
+   */
+  async getSchema(): Promise<string> {
+    return this.client.get<string>('/orders2/schema', undefined, 'xml');
+  }
+
+  /**
+   * Get order details by receipt number
+   */
+  async getOrder(receipt: string, sku?: string): Promise<OrderData> {
+    const params = sku ? { sku } : undefined;
+    const response = await this.client.get<OrderDataResponse>(`/orders2/${receipt}`, params);
+    const data = response.orderData;
+    if (Array.isArray(data) && data[0]) {
+      return data[0];
+    }
+    if (data && !Array.isArray(data)) {
+      return data;
+    }
+    throw new Error('Order not found');
+  }
+
+  /**
+   * Get all upsell transactions for a given receipt
+   */
+  async getUpsells(receipt: string): Promise<OrderData[]> {
+    const response = await this.client.get<OrderDataResponse>(`/orders2/${receipt}/upsells`);
+    if (!response.orderData) return [];
+    return Array.isArray(response.orderData) ? response.orderData : [response.orderData];
+  }
+
+  /**
+   * Count orders matching the search criteria
+   */
+  async count(params?: OrdersListParams): Promise<number> {
+    const response = await this.client.get<{ count: number }>('/orders2/count', params as Record<string, string | number | boolean | undefined>);
+    return response.count || 0;
+  }
+
+  /**
+   * List orders matching the search criteria
+   */
+  async list(params?: OrdersListParams): Promise<{ orders: OrderData[]; hasMore: boolean }> {
+    const { page, ...queryParams } = params || {};
+    const headers = page ? { page: String(page) } : undefined;
+
+    const response = await this.client.request<OrderListResponse>('/orders2/list', {
+      method: 'GET',
+      params: queryParams as Record<string, string | number | boolean | undefined>,
+      headers,
+    });
+
+    const orders = response.orderData || [];
+    return {
+      orders: Array.isArray(orders) ? orders : [orders],
+      hasMore: !!response._hasMore,
+    };
+  }
+
+  /**
+   * Change subscription from one product to another
+   */
+  async changeProduct(receipt: string, params: ChangeProductParams): Promise<void> {
+    await this.client.post(`/orders2/${receipt}/changeProduct`, { ...params });
+  }
+
+  /**
+   * Change customer's shipping address
+   */
+  async changeAddress(receipt: string, params: ChangeAddressParams): Promise<void> {
+    await this.client.post(`/orders2/${receipt}/changeAddress`, { ...params });
+  }
+
+  /**
+   * Change the date of the next rebill for a recurring product
+   */
+  async changeDate(receipt: string, params: ChangeDateParams): Promise<void> {
+    await this.client.post(`/orders2/${receipt}/changeDate`, { ...params });
+  }
+
+  /**
+   * Extend a subscription by a specified number of periods
+   */
+  async extend(receipt: string, params: ExtendParams): Promise<void> {
+    await this.client.post(`/orders2/${receipt}/extend`, { ...params });
+  }
+
+  /**
+   * Pause a subscription until a specified date
+   */
+  async pause(receipt: string, params: PauseParams): Promise<void> {
+    await this.client.post(`/orders2/${receipt}/pause`, { ...params });
+  }
+
+  /**
+   * Reinstate a cancelled subscription
+   */
+  async reinstate(receipt: string, params?: ReinstateParams): Promise<void> {
+    await this.client.post(`/orders2/${receipt}/reinstate`, params as Record<string, unknown>);
+  }
+
+  /**
+   * Check if a subscription is active
+   */
+  async isActive(receipt: string, sku?: string): Promise<boolean> {
+    const params = sku ? { sku } : undefined;
+    const response = await this.client.head<{ active: boolean }>(`/orders2/${receipt}`, params);
+    return response.active;
+  }
+}

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

@@ -0,0 +1,66 @@
+import { ClickBankClient } from './client';
+import type {
+  Product,
+  CreateProductParams,
+  ProductsListParams,
+} from '../types';
+
+interface ProductResponse {
+  product?: Product | Product[];
+}
+
+interface ProductListResponse {
+  products?: Product[];
+  _hasMore?: boolean;
+}
+
+export class ProductsApi {
+  constructor(private readonly client: ClickBankClient) {}
+
+  /**
+   * Get the XML schema for product results
+   */
+  async getSchema(): Promise<string> {
+    return this.client.get<string>('/products/schema', undefined, 'xml');
+  }
+
+  /**
+   * Get a product by SKU
+   */
+  async get(sku: string, site: string): Promise<Product> {
+    const response = await this.client.get<ProductResponse>(`/products/${sku}`, { site });
+    const data = response.product;
+    if (Array.isArray(data) && data[0]) {
+      return data[0];
+    }
+    if (data && !Array.isArray(data)) {
+      return data;
+    }
+    throw new Error('Product not found');
+  }
+
+  /**
+   * List all products for an account
+   */
+  async list(params: ProductsListParams): Promise<Product[]> {
+    const response = await this.client.get<ProductListResponse>('/products/list', { ...params });
+    const products = response.products || [];
+    return Array.isArray(products) ? products : [products];
+  }
+
+  /**
+   * Create a new product
+   */
+  async create(params: CreateProductParams): Promise<string> {
+    const { sku, ...body } = params;
+    const response = await this.client.put<{ sku: string }>(`/products/${sku}`, body as Record<string, unknown>);
+    return response.sku || sku;
+  }
+
+  /**
+   * Delete a product
+   */
+  async delete(sku: string, site: string): Promise<void> {
+    await this.client.delete(`/products/${sku}`, { site });
+  }
+}

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

@@ -0,0 +1,121 @@
+import { ClickBankClient } from './client';
+import type {
+  QuickstatsAccount,
+  QuickstatsData,
+  QuickstatsCount,
+  QuickstatsParams,
+} from '../types';
+
+interface AccountsResponse {
+  account?: QuickstatsAccount | QuickstatsAccount[];
+}
+
+interface QuickstatsListResponse {
+  quickstatsData?: QuickstatsData[];
+  _hasMore?: boolean;
+}
+
+export class QuickstatsApi {
+  constructor(private readonly client: ClickBankClient) {}
+
+  /**
+   * Get the XML schema for quickstats results
+   */
+  async getSchema(): Promise<string> {
+    return this.client.get<string>('/quickstats/schema', undefined, 'xml');
+  }
+
+  /**
+   * Get list of accounts the API user has read access to
+   */
+  async getAccounts(): Promise<QuickstatsAccount[]> {
+    const response = await this.client.get<AccountsResponse>('/quickstats/accounts');
+    if (!response.account) return [];
+    return Array.isArray(response.account) ? response.account : [response.account];
+  }
+
+  /**
+   * Get total sale, refund, and chargeback counts for a time period
+   */
+  async count(params?: Omit<QuickstatsParams, 'page'>): Promise<QuickstatsCount> {
+    return this.client.get<QuickstatsCount>(
+      '/quickstats/count',
+      params as Record<string, string | number | boolean | undefined>
+    );
+  }
+
+  /**
+   * Get daily sale, refund, and chargeback data for a time period
+   */
+  async list(params?: QuickstatsParams): Promise<{ data: QuickstatsData[]; hasMore: boolean }> {
+    const { page, ...queryParams } = params || {};
+    const headers = page ? { page: String(page) } : undefined;
+
+    const response = await this.client.request<QuickstatsListResponse>('/quickstats/list', {
+      method: 'GET',
+      params: queryParams as Record<string, string | number | boolean | undefined>,
+      headers,
+    });
+
+    const data = response.quickstatsData || [];
+    return {
+      data: Array.isArray(data) ? data : [data],
+      hasMore: !!response._hasMore,
+    };
+  }
+
+  /**
+   * Get quick summary stats for today
+   */
+  async getToday(account?: string): Promise<QuickstatsCount> {
+    const today = new Date().toISOString().split('T')[0];
+    return this.count({
+      account,
+      startDate: today,
+      endDate: today,
+    });
+  }
+
+  /**
+   * Get quick summary stats for the last N days
+   */
+  async getLastDays(days: number, account?: string): Promise<QuickstatsCount> {
+    const endDate = new Date();
+    const startDate = new Date();
+    startDate.setDate(startDate.getDate() - days);
+
+    return this.count({
+      account,
+      startDate: startDate.toISOString().split('T')[0],
+      endDate: endDate.toISOString().split('T')[0],
+    });
+  }
+
+  /**
+   * Get daily stats for a date range
+   */
+  async getDailyStats(
+    startDate: string,
+    endDate: string,
+    account?: string
+  ): Promise<QuickstatsData[]> {
+    const result: QuickstatsData[] = [];
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await this.list({
+        account,
+        startDate,
+        endDate,
+        page,
+      });
+
+      result.push(...response.data);
+      hasMore = response.hasMore;
+      page++;
+    }
+
+    return result;
+  }
+}

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

@@ -0,0 +1,104 @@
+import { ClickBankClient } from './client';
+import type {
+  OrderShipData,
+  ShippingListParams,
+  ShipNoticeParams,
+} from '../types';
+
+interface ShippingResponse {
+  orderShipData?: OrderShipData | OrderShipData[];
+}
+
+interface ShippingListResponse {
+  orderShipData?: OrderShipData[];
+  _hasMore?: boolean;
+}
+
+export class ShippingApi {
+  constructor(private readonly client: ClickBankClient) {}
+
+  /**
+   * Get the XML schema for shipping data results
+   */
+  async getSchema(): Promise<string> {
+    return this.client.get<string>('/shipping2/schema', undefined, 'xml');
+  }
+
+  /**
+   * Count physical goods orders matching the shipping criteria
+   */
+  async count(params?: Omit<ShippingListParams, 'page'>): Promise<number> {
+    const response = await this.client.get<{ count: number }>(
+      '/shipping2/count',
+      params as Record<string, string | number | boolean | undefined>
+    );
+    return response.count || 0;
+  }
+
+  /**
+   * List physical goods orders matching the shipping criteria
+   */
+  async list(params?: ShippingListParams): Promise<{ orders: OrderShipData[]; hasMore: boolean }> {
+    const { page, ...queryParams } = params || {};
+    const headers = page ? { page: String(page) } : undefined;
+
+    const response = await this.client.request<ShippingListResponse>('/shipping2/list', {
+      method: 'GET',
+      params: queryParams as Record<string, string | number | boolean | undefined>,
+      headers,
+    });
+
+    const orders = response.orderShipData || [];
+    return {
+      orders: Array.isArray(orders) ? orders : [orders],
+      hasMore: !!response._hasMore,
+    };
+  }
+
+  /**
+   * Get shipping details for a specific receipt
+   */
+  async getByReceipt(receipt: string): Promise<OrderShipData | null> {
+    const response = await this.list({ receipt });
+    return response.orders[0] || null;
+  }
+
+  /**
+   * Get unshipped orders
+   */
+  async getUnshipped(params?: Omit<ShippingListParams, 'status'>): Promise<{ orders: OrderShipData[]; hasMore: boolean }> {
+    return this.list({ ...params, status: 'notshipped' });
+  }
+
+  /**
+   * Get shipped orders
+   */
+  async getShipped(params?: Omit<ShippingListParams, 'status'>): Promise<{ orders: OrderShipData[]; hasMore: boolean }> {
+    return this.list({ ...params, status: 'shipped' });
+  }
+
+  /**
+   * Create a shipping notification
+   */
+  async createShipNotice(params: ShipNoticeParams): Promise<void> {
+    await this.client.post('/shipping2/shipnotice', { ...params });
+  }
+
+  /**
+   * Mark an order as shipped
+   */
+  async markShipped(
+    receipt: string,
+    itemNo: string,
+    trackingId?: string,
+    carrier?: string
+  ): Promise<void> {
+    await this.createShipNotice({
+      receipt,
+      itemNo,
+      trackingId,
+      carrier,
+      date: new Date().toISOString().split('T')[0],
+    });
+  }
+}

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

@@ -0,0 +1,180 @@
+import { ClickBankClient } from './client';
+import type {
+  Ticket,
+  TicketsListParams,
+  TicketsCountParams,
+  CreateTicketParams,
+  UpdateTicketParams,
+  RefundAmountsParams,
+  RefundAmountData,
+} from '../types';
+
+interface TicketResponse {
+  ticketData?: Ticket;
+}
+
+interface TicketListResponse {
+  ticketData?: Ticket[];
+  _hasMore?: boolean;
+}
+
+export class TicketsApi {
+  constructor(private readonly client: ClickBankClient) {}
+
+  /**
+   * Get the XML schema for ticket data results
+   */
+  async getSchema(): Promise<string> {
+    return this.client.get<string>('/tickets/schema', undefined, 'xml');
+  }
+
+  /**
+   * Get the XML schema for partial refund data results
+   */
+  async getPartialRefundSchema(): Promise<string> {
+    return this.client.get<string>('/tickets/partialRefundDataSchema', undefined, 'xml');
+  }
+
+  /**
+   * Get a ticket by ID
+   */
+  async get(ticketId: string): Promise<Ticket> {
+    const response = await this.client.get<TicketResponse>(`/tickets/${ticketId}`);
+    return response.ticketData as Ticket;
+  }
+
+  /**
+   * Count tickets matching the search criteria
+   */
+  async count(params?: TicketsCountParams): Promise<number> {
+    const response = await this.client.get<{ count: number }>('/tickets/count', params as Record<string, string | number | boolean | undefined>);
+    return response.count || 0;
+  }
+
+  /**
+   * List tickets matching the search criteria
+   */
+  async list(params?: TicketsListParams): Promise<{ tickets: Ticket[]; hasMore: boolean }> {
+    const { page, ...queryParams } = params || {};
+    const headers = page ? { page: String(page) } : undefined;
+
+    const response = await this.client.request<TicketListResponse>('/tickets/list', {
+      method: 'GET',
+      params: queryParams as Record<string, string | number | boolean | undefined>,
+      headers,
+    });
+
+    const tickets = response.ticketData || [];
+    return {
+      tickets: Array.isArray(tickets) ? tickets : [tickets],
+      hasMore: !!response._hasMore,
+    };
+  }
+
+  /**
+   * Get refund amounts for a receipt
+   */
+  async getRefundAmounts(receipt: string, params: RefundAmountsParams): Promise<RefundAmountData> {
+    return this.client.get<RefundAmountData>(
+      `/tickets/refundAmounts/${receipt}`,
+      { ...params }
+    );
+  }
+
+  /**
+   * Create a new ticket
+   */
+  async create(receipt: string, params: CreateTicketParams): Promise<Ticket> {
+    const response = await this.client.post<TicketResponse>(
+      `/tickets/${receipt}`,
+      { ...params }
+    );
+    return response.ticketData as Ticket;
+  }
+
+  /**
+   * Update a ticket (close, comment, change type, or reopen)
+   */
+  async update(ticketId: string, params: UpdateTicketParams): Promise<Ticket> {
+    const response = await this.client.put<TicketResponse>(
+      `/tickets/${ticketId}`,
+      params as Record<string, unknown>
+    );
+    return response.ticketData as Ticket;
+  }
+
+  /**
+   * Close a ticket
+   */
+  async close(ticketId: string, comment?: string): Promise<Ticket> {
+    return this.update(ticketId, { action: 'close', comment });
+  }
+
+  /**
+   * Reopen a ticket
+   */
+  async reopen(ticketId: string, comment: string): Promise<Ticket> {
+    return this.update(ticketId, { action: 'reopen', comment });
+  }
+
+  /**
+   * Add a comment to a ticket
+   */
+  async addComment(ticketId: string, comment: string): Promise<Ticket> {
+    return this.update(ticketId, { comment });
+  }
+
+  /**
+   * Acknowledge return of a physical item and complete refund
+   */
+  async confirmReturn(ticketId: string): Promise<void> {
+    await this.client.post(`/tickets/${ticketId}/returned`);
+  }
+
+  /**
+   * Create a refund ticket
+   */
+  async createRefund(
+    receipt: string,
+    refundType: 'FULL' | 'PARTIAL_PERCENT' | 'PARTIAL_AMOUNT',
+    reason: string,
+    options?: { refundAmount?: number; sku?: string; comment?: string; retainSubscription?: boolean }
+  ): Promise<Ticket> {
+    return this.create(receipt, {
+      type: 'rfnd',
+      reason,
+      refundType,
+      ...options,
+    });
+  }
+
+  /**
+   * Create a cancellation ticket
+   */
+  async createCancellation(
+    receipt: string,
+    reason: string,
+    options?: { sku?: string; comment?: string }
+  ): Promise<Ticket> {
+    return this.create(receipt, {
+      type: 'cncl',
+      reason,
+      ...options,
+    });
+  }
+
+  /**
+   * Create a technical support ticket
+   */
+  async createTechSupport(
+    receipt: string,
+    reason: string,
+    comment?: string
+  ): Promise<Ticket> {
+    return this.create(receipt, {
+      type: 'tech',
+      reason,
+      comment,
+    });
+  }
+}