@jlcpcb/core 0.1.0

package/src/api/easyeda-community.ts

@@ -0,0 +1,259 @@
+/**
+ * EasyEDA Community Library API client
+ * For searching and fetching user-contributed components
+ *
+ * Uses shared parsers from common/parsers for all shape types.
+ */
+
+import type {
+  EasyEDACommunitySearchParams,
+  EasyEDACommunitySearchResult,
+  EasyEDACommunityComponent,
+} from '../types/index.js'
+import { createLogger } from '../utils/index.js'
+import {
+  fetchWithCurlFallback,
+  parseSymbolShapes,
+  parseFootprintShapes,
+} from '../parsers/index.js'
+
+const logger = createLogger('easyeda-community-api')
+
+const API_SEARCH_ENDPOINT = 'https://easyeda.com/api/components/search'
+const API_COMPONENT_ENDPOINT = 'https://easyeda.com/api/components'
+const API_VERSION = '6.5.51'
+
+// Reuse 3D model endpoints from existing easyeda client
+const ENDPOINT_3D_MODEL_STEP = 'https://modules.easyeda.com/qAxj6KHrDKw4blvCG8QJPs7Y/{uuid}'
+const ENDPOINT_3D_MODEL_OBJ = 'https://modules.easyeda.com/3dmodel/{uuid}'
+
+export class EasyEDACommunityClient {
+  /**
+   * Search the EasyEDA community library
+   */
+  async search(
+    params: EasyEDACommunitySearchParams
+  ): Promise<EasyEDACommunitySearchResult[]> {
+    const formData = new URLSearchParams()
+    formData.append('type', '3') // Component type
+    formData.append('doctype[]', '2') // Symbol+footprint
+    formData.append('uid', params.source || 'user')
+    formData.append('returnListStyle', 'classifyarr')
+    formData.append('wd', params.query)
+    formData.append('version', API_VERSION)
+
+    logger.debug(`Searching EasyEDA community: ${params.query}`)
+
+    try {
+      const responseText = (await fetchWithCurlFallback(API_SEARCH_ENDPOINT, {
+        method: 'POST',
+        body: formData.toString(),
+        contentType: 'application/x-www-form-urlencoded',
+      })) as string
+
+      const data = JSON.parse(responseText)
+
+      if (!data.success || !data.result) {
+        logger.warn('EasyEDA search returned no results')
+        return []
+      }
+
+      return this.parseSearchResults(data.result.lists, params.limit)
+    } catch (error) {
+      logger.error('EasyEDA search failed:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Get full component details by UUID
+   */
+  async getComponent(uuid: string): Promise<EasyEDACommunityComponent | null> {
+    const url = `${API_COMPONENT_ENDPOINT}/${uuid}?version=${API_VERSION}&uuid=${uuid}`
+
+    logger.debug(`Fetching component: ${uuid}`)
+
+    try {
+      const responseText = (await fetchWithCurlFallback(url)) as string
+      const data = JSON.parse(responseText)
+
+      if (!data.success || !data.result) {
+        return null
+      }
+
+      return this.parseComponent(data.result)
+    } catch (error) {
+      logger.error(`Failed to fetch component ${uuid}:`, error)
+      throw error
+    }
+  }
+
+  /**
+   * Download 3D model for a component
+   */
+  async get3DModel(
+    uuid: string,
+    format: 'step' | 'obj' = 'step'
+  ): Promise<Buffer | null> {
+    const url =
+      format === 'step'
+        ? ENDPOINT_3D_MODEL_STEP.replace('{uuid}', uuid)
+        : ENDPOINT_3D_MODEL_OBJ.replace('{uuid}', uuid)
+
+    try {
+      const result = await fetchWithCurlFallback(url, { binary: true })
+      return result as Buffer
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Parse search results from the API response
+   */
+  private parseSearchResults(
+    lists: Record<string, unknown[]>,
+    limit?: number
+  ): EasyEDACommunitySearchResult[] {
+    const results: EasyEDACommunitySearchResult[] = []
+
+    // Process all source lists (user, lcsc, easyeda, etc.)
+    for (const [_source, items] of Object.entries(lists)) {
+      if (!Array.isArray(items)) continue
+
+      for (const item of items) {
+        const result = this.parseSearchItem(item)
+        if (result) {
+          results.push(result)
+        }
+
+        if (limit && results.length >= limit) {
+          return results
+        }
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Parse a single search result item
+   */
+  private parseSearchItem(item: any): EasyEDACommunitySearchResult | null {
+    try {
+      const cPara = item.dataStr?.head?.c_para || {}
+      const puuid = item.dataStr?.head?.puuid // Package/footprint UUID
+
+      return {
+        uuid: item.uuid || '',
+        title: item.title || '',
+        thumb: item.thumb || '',
+        description: item.description || '',
+        tags: item.tags || [],
+        package: cPara.package || '',
+        packageUuid: puuid || undefined,
+        manufacturer: cPara.Manufacturer || cPara.BOM_Manufacturer || undefined,
+        owner: {
+          uuid: item.owner?.uuid || '',
+          username: item.owner?.username || '',
+          nickname: item.owner?.nickname || '',
+          avatar: item.owner?.avatar,
+          team: item.owner?.team,
+        },
+        contributor: cPara.Contributor,
+        has3DModel: false, // Will be determined when fetching full component
+        docType: item.docType || 2,
+        updateTime: item.dataStr?.head?.utime,
+      }
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Parse full component data from the API response
+   * Uses shared parsers for consistent shape parsing with LCSC client.
+   */
+  private parseComponent(result: any): EasyEDACommunityComponent {
+    const dataStr = result.dataStr || {}
+    const packageDetail = result.packageDetail || {}
+    const cPara = dataStr.head?.c_para || {}
+
+    // Parse symbol shapes using shared parser
+    const symbolData = parseSymbolShapes(dataStr.shape || [])
+
+    // Parse footprint shapes using shared parser
+    const fpDataStr = packageDetail.dataStr || {}
+    const fpCPara = fpDataStr.head?.c_para || {}
+    const footprintData = parseFootprintShapes(fpDataStr.shape || [])
+
+    // Get origins for coordinate normalization
+    const symbolOrigin = {
+      x: parseFloat(dataStr.head?.x) || 0,
+      y: parseFloat(dataStr.head?.y) || 0,
+    }
+    const footprintOrigin = {
+      x: parseFloat(fpDataStr.head?.x) || 0,
+      y: parseFloat(fpDataStr.head?.y) || 0,
+    }
+
+    return {
+      uuid: result.uuid || '',
+      title: result.title || cPara.name || '',
+      description: result.description || '',
+      tags: result.tags || [],
+      owner: {
+        uuid: result.owner?.uuid || '',
+        username: result.owner?.username || '',
+        nickname: result.owner?.nickname || '',
+        avatar: result.owner?.avatar,
+        team: result.owner?.team,
+      },
+      creator: result.creator
+        ? {
+            uuid: result.creator.uuid || '',
+            username: result.creator.username || '',
+            nickname: result.creator.nickname || '',
+            avatar: result.creator.avatar,
+            team: result.creator.team,
+          }
+        : undefined,
+      updateTime: result.updateTime || fpDataStr.head?.utime || 0,
+      docType: result.docType || 2,
+      verify: result.verify || false,
+      symbol: {
+        pins: symbolData.pins,
+        rectangles: symbolData.rectangles,
+        circles: symbolData.circles,
+        ellipses: symbolData.ellipses,
+        arcs: symbolData.arcs,
+        polylines: symbolData.polylines,
+        polygons: symbolData.polygons,
+        paths: symbolData.paths,
+        origin: symbolOrigin,
+        head: dataStr.head || {},
+      },
+      footprint: {
+        uuid: packageDetail.uuid || '',
+        name: fpCPara.package || packageDetail.title || 'Unknown',
+        type: footprintData.type,
+        pads: footprintData.pads,
+        tracks: footprintData.tracks,
+        holes: footprintData.holes,
+        circles: footprintData.circles,
+        arcs: footprintData.arcs,
+        rects: footprintData.rects,
+        texts: footprintData.texts,
+        vias: footprintData.vias,
+        solidRegions: footprintData.solidRegions,
+        model3d: footprintData.model3d,
+        origin: footprintOrigin,
+        head: fpDataStr.head || {},
+      },
+      model3d: footprintData.model3d,
+      rawData: result,
+    }
+  }
+}
+
+export const easyedaCommunityClient = new EasyEDACommunityClient()

package/src/api/easyeda.ts

@@ -0,0 +1,153 @@
+/**
+ * EasyEDA API client for component library fetching
+ *
+ * Uses shared parsers from common/parsers for all shape types.
+ */
+
+import type { EasyEDAComponentData } from '../types/index.js';
+import { createLogger } from '../utils/index.js';
+import {
+  fetchWithCurlFallback,
+  parseSymbolShapes,
+  parseFootprintShapes,
+} from '../parsers/index.js';
+
+const logger = createLogger('easyeda-api');
+
+const API_ENDPOINT = 'https://easyeda.com/api/products/{lcsc_id}/components?version=6.4.19.5';
+const ENDPOINT_3D_MODEL_STEP = 'https://modules.easyeda.com/qAxj6KHrDKw4blvCG8QJPs7Y/{uuid}';
+const ENDPOINT_3D_MODEL_OBJ = 'https://modules.easyeda.com/3dmodel/{uuid}';
+
+export class EasyEDAClient {
+  private userAgent = 'ai-eda-lcsc-mcp/1.0.0';
+
+  /**
+   * Fetch component data from EasyEDA API
+   */
+  async getComponentData(lcscPartNumber: string): Promise<EasyEDAComponentData | null> {
+    const url = API_ENDPOINT.replace('{lcsc_id}', lcscPartNumber);
+
+    logger.debug(`Fetching component data for: ${lcscPartNumber}`);
+
+    try {
+      const responseText = await fetchWithCurlFallback(url) as string;
+      const data = JSON.parse(responseText);
+
+      if (!data.result) {
+        return null;
+      }
+
+      return this.parseComponentData(data.result, lcscPartNumber);
+    } catch (error) {
+      logger.error(`Failed to fetch component ${lcscPartNumber}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Download 3D model for a component
+   */
+  async get3DModel(uuid: string, format: 'step' | 'obj' = 'step'): Promise<Buffer | null> {
+    const url = format === 'step'
+      ? ENDPOINT_3D_MODEL_STEP.replace('{uuid}', uuid)
+      : ENDPOINT_3D_MODEL_OBJ.replace('{uuid}', uuid);
+
+    try {
+      const result = await fetchWithCurlFallback(url, { binary: true });
+      return result as Buffer;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Parse raw EasyEDA API response into structured data
+   */
+  private parseComponentData(result: any, lcscId: string): EasyEDAComponentData {
+    const dataStr = result.dataStr;
+    const packageDetail = result.packageDetail;
+    const lcscInfo = result.lcsc || {};
+    const cPara = dataStr?.head?.c_para || {};
+
+    // Parse symbol shapes using shared parser
+    const symbolData = parseSymbolShapes(dataStr?.shape || []);
+
+    // Parse footprint shapes using shared parser
+    const fpDataStr = packageDetail?.dataStr;
+    const fpCPara = fpDataStr?.head?.c_para || {};
+    const footprintData = parseFootprintShapes(fpDataStr?.shape || []);
+
+    // Get origins for coordinate normalization
+    const symbolOrigin = {
+      x: parseFloat(dataStr?.head?.x) || 0,
+      y: parseFloat(dataStr?.head?.y) || 0,
+    };
+    const footprintOrigin = {
+      x: parseFloat(fpDataStr?.head?.x) || 0,
+      y: parseFloat(fpDataStr?.head?.y) || 0,
+    };
+
+    // Extract attributes from c_para (BOM_ prefixed fields)
+    const attributes: Record<string, string> = {};
+    for (const [key, value] of Object.entries(cPara)) {
+      if (key.startsWith('BOM_') && value && typeof value === 'string') {
+        // Clean up key name: "BOM_Resistance" -> "Resistance"
+        const cleanKey = key.replace(/^BOM_/, '');
+        if (cleanKey !== 'Manufacturer' && cleanKey !== 'JLCPCB Part Class') {
+          attributes[cleanKey] = value;
+        }
+      }
+    }
+
+    return {
+      info: {
+        name: cPara.name || lcscId,
+        prefix: cPara.pre || 'U',
+        package: cPara.package || fpCPara?.package,
+        manufacturer: cPara.BOM_Manufacturer || cPara.Manufacturer,
+        datasheet: lcscInfo.url,
+        lcscId: lcscInfo.number || lcscId,
+        jlcId: cPara['BOM_JLCPCB Part Class'],
+        description: result.title || cPara.name,
+        category: result.category || undefined,
+        attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
+        // CDFER parity fields
+        stock: lcscInfo.stock,
+        price: lcscInfo.price,
+        minOrderQty: lcscInfo.min,
+        process: result.SMT ? 'SMT' : 'THT',
+        partClass: cPara['JLCPCB Part Class'],
+        partNumber: cPara['Manufacturer Part'],
+      },
+      symbol: {
+        pins: symbolData.pins,
+        rectangles: symbolData.rectangles,
+        circles: symbolData.circles,
+        ellipses: symbolData.ellipses,
+        arcs: symbolData.arcs,
+        polylines: symbolData.polylines,
+        polygons: symbolData.polygons,
+        paths: symbolData.paths,
+        origin: symbolOrigin,
+      },
+      footprint: {
+        name: fpCPara?.package || 'Unknown',
+        type: result.SMT && !packageDetail?.title?.includes('-TH_') ? 'smd' : 'tht',
+        pads: footprintData.pads,
+        tracks: footprintData.tracks,
+        holes: footprintData.holes,
+        circles: footprintData.circles,
+        arcs: footprintData.arcs,
+        rects: footprintData.rects,
+        texts: footprintData.texts,
+        vias: footprintData.vias,
+        solidRegions: footprintData.solidRegions,
+        origin: footprintOrigin,
+      },
+      model3d: footprintData.model3d,
+      rawData: result,
+    };
+  }
+}
+
+export const easyedaClient = new EasyEDAClient();

package/src/api/index.ts

@@ -0,0 +1,7 @@
+/**
+ * API clients for JLC and EasyEDA
+ */
+
+export { JLCClient, jlcClient } from './jlc.js';
+export { EasyEDAClient, easyedaClient } from './easyeda.js';
+export { EasyEDACommunityClient, easyedaCommunityClient } from './easyeda-community.js';

package/src/api/jlc.ts

@@ -0,0 +1,185 @@
+/**
+ * JLC API client for component search and details
+ * Uses JLCPCB's parts library API which provides LCSC component data
+ */
+
+import type { LCSCSearchOptions, ComponentSearchResult } from '../types/index.js';
+import { createLogger } from '../utils/index.js';
+
+const logger = createLogger('jlc-api');
+
+// JLCPCB parts API - provides LCSC component data with better reliability
+const JLCPCB_SEARCH_API =
+  'https://jlcpcb.com/api/overseas-pcb-order/v1/shoppingCart/smtGood/selectSmtComponentList/v2';
+
+/**
+ * JLCPCB component structure from API response
+ */
+interface JLCPCBComponent {
+  componentCode: string; // LCSC part number (e.g., "C82899")
+  componentModelEn: string; // Part model (e.g., "ESP32-WROOM-32-N4")
+  componentBrandEn: string; // Manufacturer
+  componentSpecificationEn: string; // Package type
+  stockCount: number;
+  componentPrices: Array<{
+    startNumber: number;
+    endNumber: number;
+    productPrice: number;
+  }>;
+  describe: string;
+  dataManualUrl?: string;
+  lcscGoodsUrl?: string;
+  componentTypeEn?: string;
+  componentLibraryType?: string; // "base" = basic part (no setup fee), "expand" = extended (setup fee required)
+  attributes?: Array<{
+    attribute_name_en: string;
+    attribute_value_name: string;
+  }>;
+}
+
+interface JLCPCBSearchResponse {
+  code: number;
+  data: {
+    componentPageInfo: {
+      total: number;
+      list: JLCPCBComponent[] | null;
+    };
+  };
+  message: string | null;
+}
+
+export interface LCSCProduct {
+  productCode: string;
+  productModel: string;
+  brandNameEn: string;
+  encapStandard: string;
+  productPriceList: Array<{
+    ladder: number;
+    productPrice: number;
+    currencySymbol: string;
+  }>;
+  stockNumber: number;
+  productIntroEn: string;
+}
+
+export class JLCClient {
+  /**
+   * Search for components via JLCPCB API
+   */
+  async search(
+    query: string,
+    options: LCSCSearchOptions = {}
+  ): Promise<ComponentSearchResult[]> {
+    const { limit = 10, page = 1, inStock = false, basicOnly = false } = options;
+
+    logger.debug(`Searching LCSC (via JLCPCB) for: ${query} (inStock=${inStock}, basicOnly=${basicOnly})`);
+
+    const requestBody: Record<string, unknown> = {
+      currentPage: page,
+      pageSize: Math.min(limit, 50),
+      keyword: query,
+      searchType: 2, // Better search relevance matching
+    };
+
+    // Add in-stock filter
+    if (inStock) {
+      requestBody.presaleType = 'stock';
+    }
+
+    // Add basic/preferred library filter (JLCPCB basic parts = lower assembly cost)
+    if (basicOnly) {
+      requestBody.componentLibTypes = ['base'];
+      requestBody.preferredComponentFlag = true;
+    }
+
+    const body = JSON.stringify(requestBody);
+
+    try {
+      const response = await fetch(JLCPCB_SEARCH_API, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+        },
+        body,
+      });
+
+      if (!response.ok) {
+        throw new Error(`JLCPCB API returned ${response.status}`);
+      }
+
+      const data: JLCPCBSearchResponse = await response.json();
+
+      if (data.code !== 200) {
+        throw new Error(`JLCPCB API error: ${data.message || 'Unknown error'}`);
+      }
+
+      const components = data.data?.componentPageInfo?.list || [];
+
+      logger.debug(`Found ${components.length} components`);
+
+      return components.map((c) => ({
+        lcscId: c.componentCode,
+        name: c.componentModelEn,
+        manufacturer: c.componentBrandEn,
+        package: c.componentSpecificationEn || '',
+        price: c.componentPrices?.[0]?.productPrice,
+        stock: c.stockCount,
+        description: c.describe,
+        productUrl: c.lcscGoodsUrl,      // LCSC product page
+        datasheetPdf: c.dataManualUrl,   // Actual PDF datasheet
+        category: c.componentTypeEn,
+        // JLCPCB assembly part type: "basic" = no setup fee, "extended" = setup fee required
+        libraryType: c.componentLibraryType === 'base' ? 'basic' : 'extended',
+        // Component specifications as key-value pairs
+        attributes: c.attributes?.reduce(
+          (acc, attr) => {
+            if (attr.attribute_value_name && attr.attribute_value_name !== '-') {
+              acc[attr.attribute_name_en] = attr.attribute_value_name;
+            }
+            return acc;
+          },
+          {} as Record<string, string>
+        ),
+      }));
+    } catch (error) {
+      logger.error(`Search failed: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Get stock and pricing information for a component
+   */
+  async getStock(lcscPartNumber: string): Promise<{
+    stock: number;
+    priceBreaks: Array<{ quantity: number; price: number }>;
+  }> {
+    // Re-search to get current stock info
+    const results = await this.search(lcscPartNumber, { limit: 1 });
+
+    if (results.length === 0) {
+      throw new Error(`Component ${lcscPartNumber} not found`);
+    }
+
+    const product = results[0];
+    return {
+      stock: product.stock,
+      priceBreaks: [{ quantity: 1, price: product.price || 0 }],
+    };
+  }
+
+  /**
+   * Get detailed component information including attributes
+   * Used to enrich EasyEDA data with JLC-specific attributes
+   */
+  async getComponentDetails(lcscPartNumber: string): Promise<ComponentSearchResult | null> {
+    const results = await this.search(lcscPartNumber, { limit: 1 });
+    if (results.length === 0) {
+      return null;
+    }
+    return results[0];
+  }
+}
+
+export const jlcClient = new JLCClient();