@jlcpcb/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @jlcpcb/core
+
+## 0.1.0
+
+### Minor Changes
+
+- [`cc44735`](https://github.com/l3wi/jlc-cli/commit/cc44735cc56191533f1a088101dfe2b368929048) Thanks [@l3wi](https://github.com/l3wi)! - Initial release of @jlcpcb packages for JLC/EasyEDA component sourcing and KiCad integration.
+  - **@jlcpcb/core**: Core library with API clients, converters, and services
+  - **@jlcpcb/cli**: Interactive terminal UI for component search and library management
+  - **@jlcpcb/mcp**: MCP server for Claude Desktop/Code integration

package/README.md

@@ -0,0 +1,474 @@
+# @jlcpcb/core
+
+> **Unofficial package** - This is a community-maintained tool and is not affiliated with, endorsed by, or officially connected to JLCPCB, LCSC, or EasyEDA.
+
+Core library for JLC/EasyEDA component sourcing and KiCad conversion. Provides API clients, symbol/footprint converters, and library management services.
+
+## Installation
+
+```bash
+npm install @jlcpcb/core
+# or
+bun add @jlcpcb/core
+```
+
+## Quick Start
+
+```typescript
+import {
+  createComponentService,
+  createLibraryService
+} from '@jlcpcb/core';
+
+// Search for components
+const componentService = createComponentService();
+const results = await componentService.search('STM32F103', {
+  limit: 10,
+  inStock: true,
+  basicOnly: true,
+});
+
+// Install to KiCad library
+const libraryService = createLibraryService();
+const result = await libraryService.install('C8734', {
+  include3d: true,
+});
+
+console.log(result.symbolRef);    // "JLC-MCP-ICs:STM32F103C8T6"
+console.log(result.footprintRef); // "Package_QFP:LQFP-48_7x7mm_P0.5mm"
+```
+
+## API Reference
+
+### Services
+
+High-level APIs for common operations.
+
+#### ComponentService
+
+Search and fetch component data from LCSC/EasyEDA.
+
+```typescript
+import { createComponentService } from '@jlcpcb/core';
+
+const service = createComponentService();
+
+// Search LCSC catalog
+const results = await service.search('100nF 0402', {
+  limit: 20,
+  inStock: true,
+  basicOnly: true,           // Only JLCPCB basic parts
+  source: 'lcsc',            // 'lcsc' | 'easyeda-community' | 'all'
+});
+
+// Fetch full component data
+const component = await service.fetch('C2040');
+
+// Get component details with pin/pad counts
+const details = await service.getDetails('C2040');
+
+// Fetch from EasyEDA community library
+const communityComponent = await service.fetchCommunity('uuid-here');
+```
+
+**SearchOptions:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `limit` | `number` | `20` | Maximum results |
+| `inStock` | `boolean` | `false` | Only in-stock parts |
+| `basicOnly` | `boolean` | `false` | Only JLCPCB basic parts |
+| `source` | `string` | `'lcsc'` | Search source |
+
+#### LibraryService
+
+Install components to KiCad libraries.
+
+```typescript
+import { createLibraryService } from '@jlcpcb/core';
+
+const lib = createLibraryService();
+
+// Install component to global library
+const result = await lib.install('C2040', {
+  include3d: true,
+});
+
+// Install to project-local library
+const result = await lib.install('C2040', {
+  projectPath: '/path/to/kicad/project',
+  include3d: true,
+});
+
+// List installed components
+const installed = await lib.listInstalled();
+
+// Check library status
+const status = await lib.getStatus();
+// { installed: true, linked: true, kicadVersion: '9.0', path: '...' }
+
+// Initialize/register global library tables
+await lib.ensureGlobalTables();
+```
+
+**InstallOptions:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `projectPath` | `string` | - | Project path for local install |
+| `include3d` | `boolean` | `false` | Download 3D model |
+| `force` | `boolean` | `false` | Regenerate if exists |
+
+**InstallResult:**
+
+```typescript
+interface InstallResult {
+  symbolRef: string;           // "JLC-MCP-ICs:STM32F103C8T6"
+  footprintRef: string;        // "Package_QFP:LQFP-48..."
+  symbolPath: string;          // Absolute path to .kicad_sym
+  footprintPath?: string;      // Path to .kicad_mod (if custom)
+  modelPath?: string;          // Path to .step (if included)
+  symbolAction: 'created' | 'appended' | 'exists' | 'replaced';
+  footprintType: 'builtin' | 'custom';
+  validationData: {
+    pinCount: number;
+    padCount: number;
+    pinPadCountMatch: boolean;
+    hasPowerPins: boolean;
+    hasGroundPins: boolean;
+  };
+}
+```
+
+### API Clients
+
+Low-level clients for direct API access.
+
+#### JLCClient
+
+Search JLCPCB/LCSC catalog.
+
+```typescript
+import { jlcClient } from '@jlcpcb/core';
+
+// Search components
+const results = await jlcClient.search('STM32F103', {
+  limit: 10,
+  page: 1,
+  inStock: true,
+  basicOnly: true,
+});
+
+// Get current stock and pricing
+const stock = await jlcClient.getStock('C2040');
+// { stock: 50000, priceTiers: [{ qty: 1, price: 0.15 }, ...] }
+
+// Get detailed component info with attributes
+const details = await jlcClient.getComponentDetails('C2040');
+```
+
+#### EasyEDAClient
+
+Fetch symbol/footprint data from EasyEDA.
+
+```typescript
+import { easyedaClient } from '@jlcpcb/core';
+
+// Get complete component data
+const data = await easyedaClient.getComponentData('C2040');
+// Returns: { info, symbol, footprint, model3d }
+
+// Download 3D model
+const modelBuffer = await easyedaClient.get3DModel('uuid', 'step');
+// Returns: Buffer containing STEP file
+```
+
+**EasyEDAComponentData:**
+
+```typescript
+interface EasyEDAComponentData {
+  info: {
+    lcsc: string;
+    manufacturer: string;
+    mfrPart: string;
+    package: string;
+    datasheet: string;
+    description: string;
+    category: string;
+  };
+  symbol: {
+    pins: EasyEDAPin[];
+    rectangles: EasyEDASymbolRect[];
+    circles: EasyEDASymbolCircle[];
+    arcs: EasyEDASymbolArc[];
+    polylines: EasyEDASymbolPolyline[];
+    paths: EasyEDASymbolPath[];
+  };
+  footprint: {
+    pads: EasyEDAPad[];
+    tracks: EasyEDATrack[];
+    holes: EasyEDAHole[];
+    circles: EasyEDACircle[];
+    vias: EasyEDAVia[];
+    solidRegions: EasyEDASolidRegion[];
+  };
+  model3d?: EasyEDA3DModel;
+}
+```
+
+#### EasyEDACommunityClient
+
+Search user-contributed components.
+
+```typescript
+import { easyedaCommunityClient } from '@jlcpcb/core';
+
+// Search community library
+const results = await easyedaCommunityClient.search({
+  query: 'XIAO RP2040',
+  limit: 10,
+});
+
+// Get full component by UUID
+const component = await easyedaCommunityClient.getComponent('uuid');
+
+// Download 3D model
+const model = await easyedaCommunityClient.get3DModel('uuid', 'step');
+```
+
+### Converters
+
+Convert EasyEDA format to KiCad S-expression format.
+
+#### SymbolConverter
+
+```typescript
+import { symbolConverter } from '@jlcpcb/core';
+
+// Generate complete KiCad symbol library
+const kicadSym = symbolConverter.convert(componentData, {
+  libraryName: 'MyLibrary',
+  includeDatasheet: true,
+});
+
+// Generate symbol entry only (for appending)
+const entry = symbolConverter.convertToSymbolEntry(componentData);
+
+// Append to existing library
+const updated = symbolConverter.appendToLibrary(existingContent, componentData);
+
+// Replace symbol in library
+const replaced = symbolConverter.replaceInLibrary(existingContent, componentData);
+
+// Check if symbol exists
+const exists = symbolConverter.symbolExistsInLibrary(content, 'STM32F103C8T6');
+
+// Get symbol name from component
+const name = symbolConverter.getSymbolName(componentData);
+```
+
+#### FootprintConverter
+
+```typescript
+import { footprintConverter } from '@jlcpcb/core';
+
+// Generate KiCad footprint file
+const kicadMod = footprintConverter.convert(componentData, {
+  footprintName: 'LQFP-48_Custom',
+  include3dModel: true,
+  modelPath: '${KICAD9_3RD_PARTY}/jlc_mcp/3dmodels/...',
+});
+
+// Get footprint (returns reference for built-in or generates custom)
+const result = footprintConverter.getFootprint(componentData);
+// { type: 'builtin', ref: 'Package_QFP:LQFP-48_7x7mm_P0.5mm' }
+// or
+// { type: 'custom', content: '(footprint ...)' }
+```
+
+### Utilities
+
+#### CategoryRouter
+
+Route components to category-based libraries.
+
+```typescript
+import { categoryRouter } from '@jlcpcb/core';
+
+// Determine library category from component
+const category = categoryRouter.getLibraryCategory('R', 'Resistors', '100k 0603');
+// 'Resistors'
+
+// Get library filename
+const filename = categoryRouter.getLibraryFilename('Resistors');
+// 'JLC-MCP-Resistors.kicad_sym'
+
+// Get full symbol reference
+const ref = categoryRouter.getSymbolReference('ICs', 'STM32F103C8T6');
+// 'JLC-MCP-ICs:STM32F103C8T6'
+
+// Get footprint reference
+const fpRef = categoryRouter.getFootprintReference('LQFP-48_Custom');
+// 'JLC-MCP:LQFP-48_Custom'
+
+// List all categories
+const categories = categoryRouter.getAllCategories();
+// ['Resistors', 'Capacitors', 'Inductors', 'Diodes', 'Transistors', ...]
+```
+
+**Categories:** Resistors, Capacitors, Inductors, Diodes, Crystals, Transistors, MCUs, Memory, Sensors, Interface, Power, Optocouplers, Connectors, ICs, Misc
+
+#### FootprintMapper
+
+Map package names to KiCad built-in footprints.
+
+```typescript
+import { footprintMapper } from '@jlcpcb/core';
+
+// Map package to KiCad footprint
+const fp = footprintMapper.mapToKicadFootprint('0603');
+// 'Resistor_SMD:R_0603_1608Metric'
+
+const fp2 = footprintMapper.mapToKicadFootprint('SOIC-8');
+// 'Package_SO:SOIC-8_3.9x4.9mm_P1.27mm'
+
+// Check if standard passive
+const isStandard = footprintMapper.isStandardPassive('0805');
+// true
+
+// Get reference with category context
+const ref = footprintMapper.getKicadFootprintRef('SOT-23', 'Transistors');
+// 'Package_TO_SOT_SMD:SOT-23'
+```
+
+**Supported Packages:**
+- SMD sizes: 0201, 0402, 0603, 0805, 1206, 1210, 1812, 2010, 2512
+- SOIC: 8, 14, 16, 16W, 20, 24, 28-pin
+- TSSOP: 8, 14, 16, 20, 24, 28-pin
+- SOT: SOT-23, SOT-89, SOT-223
+- SOD: SOD-123, SOD-123F
+- QFP/LQFP: 32, 48, 64, 100-pin
+- BGA: Various pitch/ball counts
+
+#### ValueNormalizer
+
+Extract and normalize component values.
+
+```typescript
+import { valueNormalizer } from '@jlcpcb/core';
+
+// Normalize component value
+const value = valueNormalizer.normalizeValue('100nF 10% 50V X7R');
+// '100nF'
+
+// Detect component type
+const type = valueNormalizer.detectComponentType('10k 0603 1%');
+// 'resistor'
+
+// Extract display value
+const display = valueNormalizer.extractDisplayValue('100uF 16V Electrolytic');
+// '100uF 16V'
+```
+
+## Types
+
+Key TypeScript types exported from `@jlcpcb/core/types`:
+
+```typescript
+import type {
+  // Component types
+  Component,
+  ComponentSearchResult,
+  ComponentDetails,
+  PriceTier,
+
+  // EasyEDA types
+  EasyEDAComponentData,
+  EasyEDAPin,
+  EasyEDAPad,
+  EasyEDASymbolRect,
+  EasyEDASymbolCircle,
+  EasyEDASymbolArc,
+
+  // Installation types
+  InstallResult,
+  InstallOptions,
+  LibraryStatus,
+
+  // Search types
+  SearchOptions,
+  SearchResult,
+} from '@jlcpcb/core/types';
+```
+
+## Architecture
+
+### Data Flow
+
+```
+LCSC Part Number (e.g., C2040)
+        │
+        ▼
+┌───────────────────────────────────┐
+│  JLCClient / EasyEDAClient        │  Fetch component data
+└───────────────────────────────────┘
+        │
+        ▼
+┌───────────────────────────────────┐
+│  SymbolConverter                  │  Convert to KiCad S-expression
+└───────────────────────────────────┘
+        │
+        ▼
+┌───────────────────────────────────┐
+│  FootprintMapper / Converter      │  Map to built-in or generate
+└───────────────────────────────────┘
+        │
+        ▼
+┌───────────────────────────────────┐
+│  CategoryRouter                   │  Route to category library
+└───────────────────────────────────┘
+        │
+        ▼
+┌───────────────────────────────────┐
+│  LibraryService                   │  Write files, update tables
+└───────────────────────────────────┘
+```
+
+### Library Organization
+
+Components are organized into category-based symbol libraries:
+
+```
+~/Documents/KiCad/9.0/3rdparty/jlc_mcp/
+├── symbols/
+│   ├── JLC-MCP-Resistors.kicad_sym
+│   ├── JLC-MCP-Capacitors.kicad_sym
+│   ├── JLC-MCP-ICs.kicad_sym
+│   └── ...
+├── footprints/
+│   └── JLC-MCP.pretty/
+│       └── [custom footprints]
+└── 3dmodels/
+    └── JLC-MCP.3dshapes/
+        └── [STEP files]
+```
+
+### Hybrid Footprint Strategy
+
+- **Standard packages** (0603, SOIC-8, etc.) use KiCad's built-in footprint library
+- **Non-standard packages** get custom footprints generated in `JLC-MCP.pretty/`
+
+This keeps library size small while ensuring full compatibility.
+
+## Development
+
+```bash
+bun run dev        # Watch mode
+bun run build      # Build to ./dist
+bun run test       # Run tests
+bun run typecheck  # Type checking
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@jlcpcb/core",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Core library for JLC/EasyEDA component sourcing and KiCad conversion",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/l3wi/jlc-cli.git",
+    "directory": "packages/jlc-core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./services": "./dist/services/index.js",
+    "./api": "./dist/api/index.js",
+    "./converter": "./dist/converter/index.js",
+    "./types": "./dist/types/index.js"
+  },
+  "scripts": {
+    "build": "tsc && bun build ./src/index.ts --outdir ./dist --target node",
+    "dev": "bun --watch build",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "jlcpcb",
+    "jlc",
+    "easyeda",
+    "kicad",
+    "electronics",
+    "components",
+    "pcb"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  }
+}