@huaqiu/part-search

Single source-of-truth client + domain service for Huaqiu's public part-search API (kiapi.eda.cn).

This package is the only implementation of the Huaqiu API integration inside HQ Edge. Other packages consume its normalized model:

                Huaqiu Public API (kiapi.eda.cn)
                           │
                           ▼
                  @huaqiu/part-search
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
   HQ Edge HTTP       @huaqiu/           (future consumers)
   /api/hqsch/parts/* huaqiu-client
                           │
                           ▼
                       HQ EDA skills
                           │
                           ▼
                          DSH plugin (thin adapter — calls HQ Edge HTTP)

Public API

import { createPartSearchService } from "@huaqiu/part-search";

const ps = createPartSearchService();

// 1. Search
const page = await ps.searchParts({
  query: "STM32",
  page: 1,
  pageSize: 20,
  requireEdaModel: true,
});

// 2. Get full detail
const part = await ps.getPart({
  manufacturerId: "7189",
  mpn: "STM32F410T8Y6TR",
});

// 3. Get only EDA models (symbol / footprint / 3D / simulation)
const models = await ps.getEdaModels({
  manufacturerId: "7189",
  mpn: "STM32F410T8Y6TR",
});

// 4. Get supply-chain offers (batched)
const offers = await ps.getSupplyChain([
  { manufacturerId: "7189", mpn: "STM32H743XIH6" },
]);

Architecture

Two layers:

• HqPartApiClient — raw wire-protocol client. Knows Huaqiu endpoints, request body shapes, response envelope. Returns Zod-parsed raw shapes. Not intended for direct consumer use.
• PartSearchService — normalized domain service. Maps raw Huaqiu responses to typed domain models (Part, EdaModels, SupplyOffer, PartSearchPage). The only layer consumers should depend on.

Error handling

Huaqiu's envelope is { code, message, ...payload }. HTTP 200 does NOT imply success — code !== 200000 is a failure. The package surfaces both failure modes as typed errors:

• PartSearchHttpError — non-2xx, network abort, invalid JSON, schema validation failure.
• PartSearchApiError — HTTP 200 but code !== 200000.
• PartSearchValidationError — response failed normalization.
• PartNotFoundError — productDetail returned result: null.
• PartModelNotFoundError — no model of the requested kind exists.

Every error carries structured context (operation, manufacturerId, mpn, status, code) so callers can branch without parsing messages.

Security

• HTTPS only.
• No authentication (Huaqiu's public API requires none).
• Per-request timeout (default 15s).
• Upstream host is restricted — there is NO generic proxy capability.
• All inputs are validated; all responses are Zod-parsed.

License

Apache-2.0