neis-school-info 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyunbin Seo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# neis-school-info
+
+[나이스 교육정보 개방 포털]의 [학교 기본 정보]를 조회하는 타입스크립트 라이브러리
+
+[나이스 교육정보 개방 포털]: https://open.neis.go.kr
+[학교 기본 정보]: https://open.neis.go.kr/portal/data/service/selectServicePage.do?infId=OPEN17020190531110010104913&infSeq=1
+
+> [!WARNING]
+> '학교기본정보'는 정기적으로 점검되지 않으므로, 휴원이나 학교 형태 변경처럼 두드러진 변경이 없었다면 잘못되었거나 오래된 정보가 남아있을 수 있다.
+
+## 개발 동기
+
+> [!WARNING]
+> '학교기본정보'는 각 시도교육청의 입력값을 엄격하게 검증하지 않고 교육부 총괄 서버로 연계한다.
+
+'학교기본정보' API 명세는 응답값의 형식을 전혀 명시하지 않는다. 다음은 문제가 되는 필드 중 일부이다.
+
+- 학교를 식별하는 `행정표준코드`가 없을 수 있으며[^no-code], 이 경우 값은 공백 문자열(`"       "`)로 채워진다.
+- 반면 `팩스번호`나 `홈페이지주소`가 없는 경우 그 값은 공백 문자열이 아닌 `null`이다.
+- `도로명우편번호`는 5자리 숫자여야 하지만 실제 값은 6자리 문자열이다.
+  - `"12345 "`처럼 뒤에 공백이 붙는 경우
+  - `" 1234 "`처럼 오입력된 경우
+  - `"      "`처럼 공백만 채워진 경우
+- `전화번호`와 `팩스번호`는 정형화되어 있지 않다.
+  - `.`, `-`, `0`, `000-0000-0000`처럼 사실상 빈 값인 경우
+  - `02-000-0000,0001` 또는 `02-000-0000/02-000-0001`처럼 여러 번호를 담은 경우
+- `홈페이지주소`도 정형화되어 있지 않다. (예: 도메인 가운데에 공백이 있거나 BOM 문자가 포함됨)
+- `영문학교명`, `도로명주소`, `도로명상세주소`에는 공백이 2개 이상 연속되거나 NBSP 문자가 섞여 있을 수 있다.
+
+[^no-code]: 개교 예정 학교이거나, 이미 개교했지만 코드가 부여되지 않은 학교
+
+이 라이브러리는 값이 없거나 유효하지 않으면 `null`로 변환한다.
+
+## 사용법
+
+```bash
+pnpm i neis-school-info
+```
+
+```ts
+import { search } from 'neis-school-info';
+
+const result = await search(
+	{
+		fields: ['학교명', '행정표준코드'], // (선택) 지정된 필드만 검증 후 반환
+		filters: { 학교명: 'OO고등학교' }, // (선택) 검색 조건; 아래 참고
+		pageIndex: 0, // (선택) 기본값 0; pIndex = pageIndex + 1
+		pageSize: 100, // (선택) 기본값 100
+	},
+	{
+		apiKey: 'NEIS_OPEN_API_KEY',
+		fetch: customFetch, // (선택) 커스텀 fetch 전달
+	},
+);
+
+if (result.ok) {
+	result.schools
+		// 행정표준코드가 없는 학교를 제외할 수 있음
+		.filter((school) => school.행정표준코드 !== null);
+}
+```
+
+> [!IMPORTANT]
+> 타입스크립트로 표현되지 않는 정규화 규칙은 [응답값](#응답값) 섹션을 참고한다 (예: 설립일자 등 날짜는 `YYYY-MM-DD` 형식).
+
+> [!NOTE]
+> 다음 경우 `search`는 결과 대신 예외를 던진다.
+>
+> - 인자가 유효하지 않은 경우 (요청 전)
+> - 네트워크 오류로 `fetch`가 실패한 경우
+> - 응답이 2xx가 아니거나 JSON이 아닌 경우
+
+### 검색 조건 (`filters`)
+
+나이스 OpenAPI와 동일하게 작동하므로 다음과 같은 특성을 가진다:
+
+- 다중 필터는 AND로 작동함
+- 빈 문자열(`""`)은 무시됨
+
+단, 신청인자로 영문 대신 한글을 사용하며, `행정표준코드`가 없는 학교는 `null`로 검색할 수 있다.
+
+```ts
+type Filters = Partial<{
+	/* 부분 일치 */
+	학교명: string; // 예: `OO` → `OO고등학교`, `OO중학교`, `OO초등학교` 검색됨
+
+	/* 완전 일치 */
+	설립명: string; // 예: `공` → `공립` 검색 안 됨
+	시도교육청코드: 시도교육청코드; // 권장
+	시도명: 시도명 | (string & {}); // 지양
+	학교종류명: string;
+	행정표준코드: string | null;
+}>;
+```
+
+> [!CAUTION]
+> `시도명`은 바뀔 수 있으며, 완전 일치이므로 괄호까지도 맞춰야 한다 (예: `전라남도` → `전남광주통합특별시(광주)`). 예전 값을 쓰면 오류 없이 빈 배열만 돌아오므로, `시도교육청코드`를 쓰는 편이 낫다. [목록](./src/enums/office-code.ts)
+
+> [!NOTE]
+> `시도교육청코드`, `설립명` 등 열거형은 패키지에서 직접 가져올 수 있다. 전체 목록은 [`src/index.ts`](./src/index.ts)를 참고한다.
+
+### 응답값
+
+이 라이브러리는 나이스 API 응답값을 검증하고 변환한다 (예: `도로명우편번호`는 공백을 제거한 후 5자리 숫자가 아니면 `null`로 변환함).
+
+```ts
+result = {
+	ok: true,
+	code: 'INFO-000',
+	meta: {
+		pageIndex: 0,
+		pageSize: 100,
+		totalCount: 12345,
+	},
+	schools: [
+		{
+			시도교육청코드: 'OO',
+			시도교육청명: 'OO특별시교육청',
+			행정표준코드: '0000000',
+			학교명: 'OO고등학교',
+			영문학교명: 'OO High School',
+			// …
+		},
+	],
+};
+```
+
+```ts
+// result.schools[number]!
+type School = {
+	/* 열거형 */
+	고등학교구분명: 고등학교구분명 | null;
+	고등학교일반전문구분명: 고등학교일반전문구분명 | null;
+	남녀공학구분명: 남녀공학구분명;
+	설립명: 설립명 | null;
+	시도교육청코드: 시도교육청코드;
+	입시전후기구분명: 입시전후기구분명;
+	주야구분명: 주야구분명;
+
+	/* 열거형 - 검증하지 않음, 목록 외 값은 문자열로 통과 */
+	학교종류명: 학교종류명 | (string & {}) | null;
+
+	/* 그 외 */
+	개교기념일: string; // `YYYY-MM-DD`
+	관할조직명: string;
+	도로명상세주소: string | null;
+	도로명우편번호: string | null; // 5자리 숫자
+	도로명주소: string | null;
+	산업체특별학급존재여부: 'Y' | 'N';
+	설립일자: string; // `YYYY-MM-DD`
+	수정일자: string; // `YYYY-MM-DD`
+	시도교육청명: string;
+	시도명: string;
+	영문학교명: string | null;
+	전화번호: string | null; // 8~15자리 숫자
+	특수목적고등학교계열명: string | null;
+	팩스번호: string | null; // 8~15자리 숫자
+	학교명: string;
+	행정표준코드: string | null;
+	홈페이지주소: string | null; // `http(s)://…`
+};
+```
+
+> [!NOTE]
+> 실패 코드는 `ERROR-<000>` 또는 `INFO-<000>` 형식이다. 코드별 설명은 [학교 기본 정보] 문서를 참고한다.
+
+```ts
+// 나이스 API가 보고한 오류
+result = { ok: false, code: 'ERROR-290', message: '…' };
+
+// 응답 형식이 예상과 다름
+result = { ok: false, code: null };
+```
+
+## 데이터 활용 시 유의사항
+
+- `학교종류명`은 검증하지 않으므로, 타입에 명시된 값 외에 다른 문자열이 올 수 있다.
+- 학교가 고등학교이면서 `고등학교일반전문구분명`이 `해당없음` 또는 `null`일 수 있다. [#1]
+- `고등학교구분명`이 `일반고`인데도 `특수목적고등학교계열명` 값이 존재할 수 있다. [#4]
+
+[#1]: https://github.com/hyunbinseo/neis-school-info/issues/1
+[#4]: https://github.com/hyunbinseo/neis-school-info/issues/4

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+//#region src/enums/office-code.d.ts
+type 시도명 = (typeof OFFICE_CODE_TO_NAMES)[시도교육청코드][0];
+declare const OFFICE_CODE_TO_NAMES: {
+  readonly B10: readonly ["서울특별시", "서울특별시교육청"];
+  readonly C10: readonly ["부산광역시", "부산광역시교육청"];
+  readonly D10: readonly ["대구광역시", "대구광역시교육청"];
+  readonly E10: readonly ["인천광역시", "인천광역시교육청"];
+  readonly F10: readonly ["전남광주통합특별시(광주)", "전남광주통합특별시교육청(광주)"];
+  readonly G10: readonly ["대전광역시", "대전광역시교육청"];
+  readonly H10: readonly ["울산광역시", "울산광역시교육청"];
+  readonly I10: readonly ["세종특별자치시", "세종특별자치시교육청"];
+  readonly J10: readonly ["경기도", "경기도교육청"];
+  readonly K10: readonly ["강원특별자치도", "강원특별자치도교육청"];
+  readonly M10: readonly ["충청북도", "충청북도교육청"];
+  readonly N10: readonly ["충청남도", "충청남도교육청"];
+  readonly P10: readonly ["전북특별자치도", "전북특별자치도교육청"];
+  readonly Q10: readonly ["전남광주통합특별시(전남)", "전남광주통합특별시교육청(전남)"];
+  readonly R10: readonly ["경상북도", "경상북도교육청"];
+  readonly S10: readonly ["경상남도", "경상남도교육청"];
+  readonly T10: readonly ["제주특별자치도", "제주특별자치도교육청"];
+  readonly V10: readonly ["재외한국학교", "재외한국학교교육청"];
+};
+export type 시도교육청코드 = (typeof 시도교육청코드)[number];
+export declare const 시도교육청코드: readonly ['B10', 'C10', 'D10', 'E10', 'F10', 'G10', 'H10', 'I10', 'J10', 'K10', 'M10', 'N10', 'P10', 'Q10', 'R10', 'S10', 'T10', 'V10'];
+//#endregion
+//#region src/enums/school-value.d.ts
+type 학교종류명 = (typeof 학교종류명)[number];
+declare const 학교종류명: readonly ['초등학교', '중학교', '고등학교', '특수학교', '고등기술학교', '고등공민학교', '공동실습소', '국제학교', '외국인학교', '방송통신중학교', '방송통신고등학교', '각종학교(초)', '각종학교(중)', '각종학교(고)', '각종학교(대안학교)', '각종학교(외국인학교)', '평생학교(초)-3년6학기', '평생학교(초)-4년12학기', '평생학교(중)-2년6학기', '평생학교(중)-3년6학기', '평생학교(고)-2년6학기', '평생학교(고)-3년6학기', '재외한국학교(초)', '재외한국학교(중)', '재외한국학교(고)'];
+export type 고등학교구분명 = (typeof 고등학교구분명)[number];
+export declare const 고등학교구분명: readonly ['일반고', '특성화고', '자율고', '특목고'];
+export type 고등학교일반전문구분명 = (typeof 고등학교일반전문구분명)[number];
+export declare const 고등학교일반전문구분명: readonly ['해당없음', '일반계', '전문계'];
+export type 남녀공학구분명 = (typeof 남녀공학구분명)[number];
+export declare const 남녀공학구분명: readonly ['남여공학', '남', '여'];
+export type 설립명 = (typeof 설립명)[number];
+export declare const 설립명: readonly ['공립', '사립', '국립', '기타', '국외'];
+export type 입시전후기구분명 = (typeof 입시전후기구분명)[number];
+export declare const 입시전후기구분명: readonly ['전기', '후기', '전후기'];
+export type 주야구분명 = (typeof 주야구분명)[number];
+export declare const 주야구분명: readonly ['주간', '야간', '주야간'];
+type YN = (typeof YN_VALUES)[number];
+declare const YN_VALUES: readonly ['Y', 'N'];
+//#endregion
+//#region src/valibot.d.ts
+type School = {
+  시도교육청코드: 시도교육청코드;
+  시도교육청명: string;
+  학교명: string;
+  영문학교명: string | null;
+  학교종류명: 학교종류명 | (string & {}) | null;
+  시도명: string;
+  관할조직명: string;
+  설립명: 설립명 | null;
+  도로명우편번호: string | null;
+  도로명주소: string | null;
+  도로명상세주소: string | null;
+  전화번호: string | null;
+  홈페이지주소: string | null;
+  남녀공학구분명: 남녀공학구분명;
+  팩스번호: string | null;
+  고등학교구분명: 고등학교구분명 | null;
+  산업체특별학급존재여부: YN;
+  고등학교일반전문구분명: 고등학교일반전문구분명 | null;
+  특수목적고등학교계열명: string | null;
+  입시전후기구분명: 입시전후기구분명;
+  주야구분명: 주야구분명;
+  설립일자: string;
+  개교기념일: string;
+  수정일자: string;
+} & ({
+  행정표준코드: string;
+} | {
+  행정표준코드: null;
+});
+//#endregion
+//#region src/params.d.ts
+type SchoolField = keyof School;
+type SchoolFields = readonly [SchoolField, ...SchoolField[]];
+type Filters = Partial<{
+  시도교육청코드: 시도교육청코드;
+  행정표준코드: string | null;
+  학교명: string;
+  학교종류명: string;
+  시도명: 시도명 | (string & {});
+  설립명: string;
+}>;
+//#endregion
+//#region src/enums/result-code.d.ts
+type SuccessCode = (typeof SUCCESS_CODES)[number];
+declare const SUCCESS_CODES: readonly ['INFO-000', 'INFO-200'];
+type FailureCode = (typeof FAILURE_CODES)[number];
+declare const FAILURE_CODES: readonly ['ERROR-300', 'ERROR-290', 'ERROR-310', 'ERROR-333', 'ERROR-336', 'ERROR-337', 'ERROR-500', 'ERROR-600', 'ERROR-601', 'INFO-100', 'INFO-300'];
+//#endregion
+//#region src/search.d.ts
+type PickedSchool<Fields extends SchoolFields, S extends School = School> = [Fields] extends [never] ? School : S extends unknown ? Pick<S, Fields[number]> : never;
+type SearchResult<Fields extends SchoolFields = never> = {
+  ok: true;
+  code: SuccessCode;
+  meta: {
+    pageIndex: number;
+    pageSize: number;
+    totalCount: number;
+  };
+  schools: PickedSchool<Fields>[];
+} | {
+  ok: false;
+  code: FailureCode;
+  message: string;
+} | {
+  ok: false;
+  code: null;
+};
+export declare const search: <const Fields extends SchoolFields = never>(params: Partial<{
+  pageIndex: number;
+  pageSize: number;
+  fields: Fields;
+  filters: Filters;
+}>, opts: {
+  apiKey: string;
+  fetch?: typeof fetch;
+}) => Promise<SearchResult<Fields>>;
+//#endregion
+export type { FailureCode, Filters, School, SearchResult, SuccessCode, 시도명, 학교종류명 };

package/dist/index.js

@@ -0,0 +1,218 @@
+import { array, check, digits, entriesFromList, fallback, integer, isoDate, length, maxLength, maxValue, minLength, minValue, nonEmpty, nullable, number, object, optional, parse, pick, picklist, pipe, safeParse, strictObject, string, transform, trim, tuple, unknown, url } from "valibot";
+//#region src/enums/filter-key.ts
+const FILTER_KEY_TO_SEARCH = {
+	시도교육청코드: "ATPT_OFCDC_SC_CODE",
+	행정표준코드: "SD_SCHUL_CODE",
+	학교명: "SCHUL_NM",
+	학교종류명: "SCHUL_KND_SC_NM",
+	시도명: "LCTN_SC_NM",
+	설립명: "FOND_SC_NM"
+};
+const FILTER_KEYS = Object.keys(FILTER_KEY_TO_SEARCH);
+//#endregion
+//#region src/enums/office-code.ts
+const 시도교육청코드 = [
+	"B10",
+	"C10",
+	"D10",
+	"E10",
+	"F10",
+	"G10",
+	"H10",
+	"I10",
+	"J10",
+	"K10",
+	"M10",
+	"N10",
+	"P10",
+	"Q10",
+	"R10",
+	"S10",
+	"T10",
+	"V10"
+];
+//#endregion
+//#region src/enums/result-code.ts
+const SUCCESS_CODES = ["INFO-000", "INFO-200"];
+const FAILURE_CODES = [
+	"ERROR-300",
+	"ERROR-290",
+	"ERROR-310",
+	"ERROR-333",
+	"ERROR-336",
+	"ERROR-337",
+	"ERROR-500",
+	"ERROR-600",
+	"ERROR-601",
+	"INFO-100",
+	"INFO-300"
+];
+//#endregion
+//#region src/enums/school-field.ts
+const SCHOOL_FIELD_EN_TO_KO = {
+	ATPT_OFCDC_SC_CODE: "시도교육청코드",
+	ATPT_OFCDC_SC_NM: "시도교육청명",
+	SD_SCHUL_CODE: "행정표준코드",
+	SCHUL_NM: "학교명",
+	ENG_SCHUL_NM: "영문학교명",
+	SCHUL_KND_SC_NM: "학교종류명",
+	LCTN_SC_NM: "시도명",
+	JU_ORG_NM: "관할조직명",
+	FOND_SC_NM: "설립명",
+	ORG_RDNZC: "도로명우편번호",
+	ORG_RDNMA: "도로명주소",
+	ORG_RDNDA: "도로명상세주소",
+	ORG_TELNO: "전화번호",
+	HMPG_ADRES: "홈페이지주소",
+	COEDU_SC_NM: "남녀공학구분명",
+	ORG_FAXNO: "팩스번호",
+	HS_SC_NM: "고등학교구분명",
+	INDST_SPECL_CCCCL_EXST_YN: "산업체특별학급존재여부",
+	HS_GNRL_BUSNS_SC_NM: "고등학교일반전문구분명",
+	SPCLY_PURPS_HS_ORD_NM: "특수목적고등학교계열명",
+	ENE_BFE_SEHF_SC_NM: "입시전후기구분명",
+	DGHT_SC_NM: "주야구분명",
+	FOND_YMD: "설립일자",
+	FOAS_MEMRD: "개교기념일",
+	LOAD_DTM: "수정일자"
+};
+const EN_SCHOOL_FIELDS = Object.keys(SCHOOL_FIELD_EN_TO_KO);
+//#endregion
+//#region src/enums/school-value.ts
+const 고등학교구분명 = [
+	"일반고",
+	"특성화고",
+	"자율고",
+	"특목고"
+];
+const 고등학교일반전문구분명 = [
+	"해당없음",
+	"일반계",
+	"전문계"
+];
+const 남녀공학구분명 = [
+	"남여공학",
+	"남",
+	"여"
+];
+const 설립명 = [
+	"공립",
+	"사립",
+	"국립",
+	"기타",
+	"국외"
+];
+const 입시전후기구분명 = [
+	"전기",
+	"후기",
+	"전후기"
+];
+const 주야구분명 = [
+	"주간",
+	"야간",
+	"주야간"
+];
+const YN_VALUES = ["Y", "N"];
+//#endregion
+//#region src/valibot.ts
+const NoRowsSchema = strictObject({ RESULT: object({
+	CODE: picklist([...SUCCESS_CODES, ...FAILURE_CODES]),
+	MESSAGE: string()
+}) });
+const HeadSchema = tuple([object({ list_total_count: number() }), object({ RESULT: object({
+	CODE: picklist(SUCCESS_CODES),
+	MESSAGE: string()
+}) })]);
+const RawSchoolSchema = pipe(strictObject(entriesFromList(EN_SCHOOL_FIELDS, unknown())), transform((v) => Object.fromEntries(Object.entries(v).map(([enKey, value]) => [SCHOOL_FIELD_EN_TO_KO[enKey], value]))));
+const NormalizeStringSchema = pipe(string(), transform((v) => v.replaceAll(/\s+/g, " ")), trim());
+const NonEmptyStringSchema = pipe(NormalizeStringSchema, nonEmpty());
+const StringEmptyToNullSchema = pipe(NormalizeStringSchema, transform((v) => v || null));
+const PhoneNumberSchema = fallback(nullable(pipe(NonEmptyStringSchema, transform((v) => v.replaceAll(/[() .+-]/g, "")), digits(), minLength(8), maxLength(15), check((v) => !/^(\d)\1+$/.test(v)))), null);
+const URLSchema = fallback(nullable(pipe(NonEmptyStringSchema, transform((v) => v.replaceAll(" ", "")), check((v) => v.includes(".")), transform((v) => /^https?:\/\//i.test(v) ? v : `https://${v}`), minLength(11), url())), null);
+const YYYYMMDDToISODateSchema = pipe(string(), trim(), digits(), length(8), transform((v) => `${v.slice(0, 4)}-${v.slice(4, 6)}-${v.slice(6)}`), isoDate());
+const SchoolSchema = object({
+	시도교육청코드: picklist(시도교육청코드),
+	시도교육청명: NonEmptyStringSchema,
+	행정표준코드: StringEmptyToNullSchema,
+	학교명: NonEmptyStringSchema,
+	영문학교명: nullable(StringEmptyToNullSchema),
+	학교종류명: nullable(NonEmptyStringSchema),
+	시도명: NonEmptyStringSchema,
+	관할조직명: NonEmptyStringSchema,
+	설립명: nullable(pipe(NonEmptyStringSchema, picklist(설립명))),
+	도로명우편번호: fallback(nullable(pipe(string(), trim(), digits(), length(5))), null),
+	도로명주소: nullable(NonEmptyStringSchema),
+	도로명상세주소: nullable(StringEmptyToNullSchema),
+	전화번호: PhoneNumberSchema,
+	홈페이지주소: URLSchema,
+	남녀공학구분명: pipe(NonEmptyStringSchema, picklist(남녀공학구분명)),
+	팩스번호: PhoneNumberSchema,
+	고등학교구분명: nullable(pipe(NonEmptyStringSchema, picklist(고등학교구분명))),
+	산업체특별학급존재여부: picklist(YN_VALUES),
+	고등학교일반전문구분명: nullable(pipe(NonEmptyStringSchema, picklist(고등학교일반전문구분명))),
+	특수목적고등학교계열명: nullable(NonEmptyStringSchema),
+	입시전후기구분명: pipe(NonEmptyStringSchema, picklist(입시전후기구분명)),
+	주야구분명: pipe(NonEmptyStringSchema, picklist(주야구분명)),
+	설립일자: YYYYMMDDToISODateSchema,
+	개교기념일: YYYYMMDDToISODateSchema,
+	수정일자: YYYYMMDDToISODateSchema
+});
+//#endregion
+//#region src/search.ts
+const search = async (params, opts) => {
+	const { pageIndex, pageSize } = parse(object({
+		pageIndex: optional(pipe(number(), integer(), minValue(0)), 0),
+		pageSize: optional(pipe(number(), integer(), minValue(1), maxValue(1e3)), 100)
+	}), params);
+	const url = new URL("https://open.neis.go.kr/hub/schoolInfo");
+	url.searchParams.set("Type", "json");
+	url.searchParams.set("KEY", opts.apiKey);
+	url.searchParams.set("pIndex", (pageIndex + 1).toString());
+	url.searchParams.set("pSize", pageSize.toString());
+	for (const key of FILTER_KEYS) {
+		const searchKey = FILTER_KEY_TO_SEARCH[key];
+		let value = params.filters?.[key];
+		if (value === null && key === "행정표준코드") value = " ".repeat(7);
+		if (!value) continue;
+		url.searchParams.set(searchKey, value);
+	}
+	const response = await (opts.fetch ?? fetch)(url);
+	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+	const raw = await response.json();
+	const noRowsResult = safeParse(NoRowsSchema, raw);
+	if (noRowsResult.success) {
+		const { RESULT } = noRowsResult.output;
+		return RESULT.CODE === "INFO-000" || RESULT.CODE === "INFO-200" ? {
+			ok: true,
+			code: RESULT.CODE,
+			meta: {
+				pageIndex,
+				pageSize,
+				totalCount: 0
+			},
+			schools: []
+		} : {
+			ok: false,
+			code: RESULT.CODE,
+			message: RESULT.MESSAGE
+		};
+	}
+	const result = safeParse(strictObject({ schoolInfo: tuple([object({ head: HeadSchema }), object({ row: array(pipe(RawSchoolSchema, params.fields ? pick(SchoolSchema, params.fields) : SchoolSchema)) })]) }), raw);
+	if (!result.success) return {
+		ok: false,
+		code: null
+	};
+	const { schoolInfo: [{ head: [{ list_total_count: totalCount }, { RESULT }] }, { row: schools }] } = result.output;
+	return {
+		ok: true,
+		code: RESULT.CODE,
+		meta: {
+			pageIndex,
+			pageSize,
+			totalCount
+		},
+		schools
+	};
+};
+//#endregion
+export { search, 고등학교구분명, 고등학교일반전문구분명, 남녀공학구분명, 설립명, 시도교육청코드, 입시전후기구분명, 주야구분명 };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "neis-school-info",
+  "version": "0.1.0",
+  "description": "대한민국 학교 기본 정보 조회 (나이스 Open API 기반)",
+  "homepage": "https://github.com/hyunbinseo/neis-school-info#readme",
+  "bugs": {
+    "url": "https://github.com/hyunbinseo/neis-school-info/issues"
+  },
+  "license": "MIT",
+  "author": "Hyunbin Seo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyunbinseo/neis-school-info.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#cli/*": "./cli/*",
+    "#src/*": "./src/*"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "valibot": "^1.4.2"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@types/node": "^24.13.3",
+    "markdown-table": "^3.0.4",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "publint": "^0.3.24",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.4.0",
+      "onFail": "download"
+    },
+    "runtime": {
+      "name": "node",
+      "version": "24.21.0",
+      "onFail": "download"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "version": "node --run test && tsdown && git add package.json",
+    "test": "node --env-file=.env --test",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix"
+  }
+}