amazon-mcp-server/src/amazon-api/catalog-api.ts

Model Context Protocol server for Amazon Seller API

import { AmazonAuthManager } from './auth-manager.js';

/**
 * Interface for product search parameters
 */
export interface ProductSearchParams {
  identifiers?: string | string[];
  identifiersType?: 'EAN' | 'UPC' | 'ISBN' | 'ASIN' | 'SKU' | 'JAN';
  keywords?: string;
  brandNames?: string[];
  marketplaceIds: string[];
  includedData?: string[];
  pageSize?: number;
  pageToken?: string;
}

/**
 * Interface for product details
 */
export interface ProductDetails {
  asin?: string;
  attributes?: Record<string, any>;
  identifiers?: Record<string, any>;
  images?: any[];
  productTypes?: string[];
  summaries?: any[];
  variations?: any[];
  [key: string]: any;
}

/**
 * Handles interactions with the Amazon Seller API Catalog Items endpoints
 */
export class AmazonCatalogApi {
  private authManager: AmazonAuthManager;
  private baseUrl: string;
  private defaultMarketplaceIds: string[];
  
  /**
   * Creates a new instance of the Amazon Catalog API
   * @param authManager Authentication manager
   * @param region API region (default: 'eu')
   * @param defaultMarketplaceIds Default marketplace IDs
   */
  constructor(
    authManager: AmazonAuthManager, 
    region: string = 'eu',
    defaultMarketplaceIds: string[] = []
  ) {
    this.authManager = authManager;
    this.baseUrl = `https://sellingpartnerapi-${region}.amazon.com`;
    this.defaultMarketplaceIds = defaultMarketplaceIds;
  }
  
  /**
   * Searches for products by EAN code
   * @param ean EAN code
   * @param marketplaceIds Marketplace IDs (optional)
   * @param includedData Data to include in the response (optional)
   * @returns Promise resolving to product details
   */
  public async getProductByEan(
    ean: string,
    marketplaceIds?: string[],
    includedData?: string[]
  ): Promise<ProductDetails[]> {
    return this.searchProducts({
      identifiers: ean,
      identifiersType: 'EAN',
      marketplaceIds: marketplaceIds || this.defaultMarketplaceIds,
      includedData: includedData || ['summaries', 'attributes', 'images', 'productTypes']
    });
  }
  
  /**
   * Searches for products by ASIN
   * @param asin ASIN code
   * @param marketplaceIds Marketplace IDs (optional)
   * @param includedData Data to include in the response (optional)
   * @returns Promise resolving to product details
   */
  public async getProductByAsin(
    asin: string,
    marketplaceIds?: string[],
    includedData?: string[]
  ): Promise<ProductDetails[]> {
    return this.searchProducts({
      identifiers: asin,
      identifiersType: 'ASIN',
      marketplaceIds: marketplaceIds || this.defaultMarketplaceIds,
      includedData: includedData || ['summaries', 'attributes', 'images', 'productTypes']
    });
  }
  
  /**
   * Searches for products by SKU
   * @param sku SKU code
   * @param marketplaceIds Marketplace IDs (optional)
   * @param includedData Data to include in the response (optional)
   * @returns Promise resolving to product details
   */
  public async getProductBySku(
    sku: string,
    marketplaceIds?: string[],
    includedData?: string[]
  ): Promise<ProductDetails[]> {
    return this.searchProducts({
      identifiers: sku,
      identifiersType: 'SKU',
      marketplaceIds: marketplaceIds || this.defaultMarketplaceIds,
      includedData: includedData || ['summaries', 'attributes', 'images', 'productTypes']
    });
  }
  
  /**
   * Searches for products by keywords
   * @param keywords Search keywords
   * @param marketplaceIds Marketplace IDs (optional)
   * @param includedData Data to include in the response (optional)
   * @returns Promise resolving to product details
   */
  public async getProductsByKeywords(
    keywords: string,
    marketplaceIds?: string[],
    includedData?: string[]
  ): Promise<ProductDetails[]> {
    return this.searchProducts({
      keywords,
      marketplaceIds: marketplaceIds || this.defaultMarketplaceIds,
      includedData: includedData || ['summaries', 'attributes', 'images', 'productTypes']
    });
  }
  
  /**
   * Searches for products by brand name
   * @param brandNames Brand names
   * @param marketplaceIds Marketplace IDs (optional)
   * @param includedData Data to include in the response (optional)
   * @returns Promise resolving to product details
   */
  public async getProductsByBrand(
    brandNames: string[],
    marketplaceIds?: string[],
    includedData?: string[]
  ): Promise<ProductDetails[]> {
    return this.searchProducts({
      brandNames,
      marketplaceIds: marketplaceIds || this.defaultMarketplaceIds,
      includedData: includedData || ['summaries', 'attributes', 'images', 'productTypes']
    });
  }
  
  /**
   * Searches for products with advanced parameters
   * @param params Search parameters
   * @returns Promise resolving to product details
   */
  public async searchProducts(params: ProductSearchParams): Promise<ProductDetails[]> {
    const { 
      identifiers, 
      identifiersType, 
      keywords, 
      brandNames, 
      marketplaceIds, 
      includedData = ['summaries'],
      pageSize,
      pageToken
    } = params;
    
    // Build query parameters
    const queryParams: Record<string, string> = {
      marketplaceIds: marketplaceIds.join(','),
      includedData: includedData.join(',')
    };
    
    if (identifiers) {
      queryParams.identifiers = Array.isArray(identifiers) 
        ? identifiers.join(',') 
        : identifiers;
        
      if (identifiersType) {
        queryParams.identifiersType = identifiersType;
      }
    }
    
    if (keywords) {
      queryParams.keywords = keywords;
    }
    
    if (brandNames && brandNames.length > 0) {
      queryParams.brandNames = brandNames.join(',');
    }
    
    if (pageSize) {
      queryParams.pageSize = pageSize.toString();
    }
    
    if (pageToken) {
      queryParams.pageToken = pageToken;
    }
    
    // Make the API request
    const endpoint = `${this.baseUrl}/catalog/2022-04-01/items`;
    const response = await this.authManager.makeAuthorizedRequest('GET', endpoint, queryParams);
    
    // Process and return the results
    const items: ProductDetails[] = [];
    
    if (response.items && Array.isArray(response.items)) {
      return response.items;
    }
    
    return items;
  }
  
  /**
   * Gets detailed information for a specific ASIN
   * @param asin ASIN code
   * @param marketplaceIds Marketplace IDs (optional)
   * @param includedData Data to include in the response (optional)
   * @returns Promise resolving to product details
   */
  public async getItemDetails(
    asin: string,
    marketplaceIds?: string[],
    includedData?: string[]
  ): Promise<ProductDetails> {
    const endpoint = `${this.baseUrl}/catalog/2022-04-01/items/${asin}`;
    
    const queryParams: Record<string, string> = {
      marketplaceIds: (marketplaceIds || this.defaultMarketplaceIds).join(','),
      includedData: (includedData || ['summaries', 'attributes', 'images', 'productTypes']).join(',')
    };
    
    const response = await this.authManager.makeAuthorizedRequest('GET', endpoint, queryParams);
    
    return response;
  }
}