From 8bad67e50560baffe4d343911fb29c7c53d0d3df Mon Sep 17 00:00:00 2001
From: Jiho Lee <optional.int@kakao.com>
Date: Fri, 24 Jul 2026 22:09:05 +0900
Subject: [PATCH] fix: explain C99 assembly-catalog part numbers in the
 not-found error
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Progress on #390.

C9900033429 (the reported part) is a JLCPCB assembly-catalog number:
both the EasyEDA search API and the products API return nothing for it
(verified 2026-07-24 — every search list empty, products API 404), so
the converter genuinely has nothing to fetch.

The bare 'Component not found' error now identifies C99-prefixed
assembly parts and suggests searching the underlying manufacturer part
number, and the generic error includes the part number that failed.
---
 lib/websafe/fetch-easyeda-json.ts             |  7 +++-
 .../c99-assembly-part-error-390.test.ts       | 38 +++++++++++++++++++
 2 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 tests/fetch-tests/c99-assembly-part-error-390.test.ts

diff --git a/lib/websafe/fetch-easyeda-json.ts b/lib/websafe/fetch-easyeda-json.ts
index b45e956f..865d23ff 100644
--- a/lib/websafe/fetch-easyeda-json.ts
+++ b/lib/websafe/fetch-easyeda-json.ts
@@ -119,7 +119,12 @@ export async function fetchEasyEDAComponent(
 
   const searchResult = await searchResponse.json()
   if (!searchResult.success || !searchResult.result.lists.lcsc.length) {
-    throw new Error("Component not found")
+    if (/^C99\d{6,}$/i.test(jlcpcbPartNumber)) {
+      throw new Error(
+        `Component not found: "${jlcpcbPartNumber}" is a JLCPCB assembly-catalog part number (C99xxxxxxx). These parts frequently have no EasyEDA symbol/footprint behind them, so there is nothing to convert — try searching for the underlying manufacturer part number instead.`,
+      )
+    }
+    throw new Error(`Component not found: "${jlcpcbPartNumber}"`)
   }
 
   const bestMatchComponent =
diff --git a/tests/fetch-tests/c99-assembly-part-error-390.test.ts b/tests/fetch-tests/c99-assembly-part-error-390.test.ts
new file mode 100644
index 00000000..253842e8
--- /dev/null
+++ b/tests/fetch-tests/c99-assembly-part-error-390.test.ts
@@ -0,0 +1,38 @@
+import { expect, it } from "bun:test"
+import { fetchEasyEDAComponent } from "lib/websafe/fetch-easyeda-json"
+
+// https://github.com/tscircuit/easyeda-converter/issues/390
+//
+// C99xxxxxxx numbers are JLCPCB assembly-catalog entries that often have no
+// EasyEDA symbol/footprint behind them (verified: both the search API and the
+// products API return nothing for C9900033429). The error should say so
+// instead of a bare "Component not found".
+it("explains that C99 assembly parts have no EasyEDA data", async () => {
+  const emptySearchFetch = (async () =>
+    new Response(
+      JSON.stringify({
+        success: true,
+        result: { lists: { lcsc: [] } },
+      }),
+      { status: 200 },
+    )) as unknown as typeof globalThis.fetch
+
+  expect(
+    fetchEasyEDAComponent("C9900033429", { fetch: emptySearchFetch }),
+  ).rejects.toThrow(/assembly-catalog part number/)
+})
+
+it("includes the part number in the generic not-found error", async () => {
+  const emptySearchFetch = (async () =>
+    new Response(
+      JSON.stringify({
+        success: true,
+        result: { lists: { lcsc: [] } },
+      }),
+      { status: 200 },
+    )) as unknown as typeof globalThis.fetch
+
+  expect(
+    fetchEasyEDAComponent("C1234", { fetch: emptySearchFetch }),
+  ).rejects.toThrow(/Component not found: "C1234"/)
+})