gongdata 0.1.0

package/dist/index.js

@@ -0,0 +1,650 @@
+import { XMLParser } from 'fast-xml-parser';
+
+// src/core/parser.ts
+
+// src/core/error.ts
+var ResultCode = {
+  /** 정상 */
+  SUCCESS: "00",
+  // === 공공데이터포털 공통 에러 ===
+  /** 어플리케이션 에러 */
+  APPLICATION_ERROR: "1",
+  /** 잘못된 요청 파라미터 */
+  INVALID_REQUEST_PARAMETER: "10",
+  /** 해당 오픈API 서비스 없음 또는 폐기 */
+  NO_OPENAPI_SERVICE: "12",
+  /** 서비스 접근 거부 */
+  SERVICE_ACCESS_DENIED: "20",
+  /** 서비스 요청 제한 횟수 초과 */
+  REQUEST_LIMIT_EXCEEDED: "22",
+  /** 등록되지 않은 서비스키 */
+  UNREGISTERED_SERVICE_KEY: "30",
+  /** 서비스키 기한 만료 */
+  EXPIRED_SERVICE_KEY: "31",
+  /** 등록되지 않은 IP */
+  UNREGISTERED_IP: "32",
+  /** 기타 에러 */
+  UNKNOWN_ERROR: "99",
+  // === SDK 내부 에러 ===
+  /** HTTP 에러 */
+  HTTP_ERROR: "HTTP_ERROR",
+  /** 서비스 타임아웃 */
+  SERVICE_TIMEOUT: "SERVICE_TIMEOUT",
+  // === HRDK(한국산업인력공단) 자체 에러 ===
+  /** 게이트웨이 인증 오류 */
+  GATEWAY_AUTH_ERROR: "900",
+  /** 필수 파라미터 누락 */
+  MISSING_REQUIRED_PARAMETER: "910",
+  /** 잘못된 dataFormat (json/xml만 가능) */
+  INVALID_DATA_FORMAT: "920",
+  /** 최대 목록 수 초과 */
+  MAX_ROWS_EXCEEDED: "930",
+  /** 잘못된 토큰 파라미터 */
+  INVALID_TOKEN: "940",
+  /** 토큰 유효기한 만료 (1시간) */
+  TOKEN_EXPIRED: "941",
+  /** 파일을 찾을 수 없음 */
+  FILE_NOT_FOUND: "950",
+  /** HRDK 서버 에러 */
+  HRDK_SERVER_ERROR: "990"
+};
+var RESULT_MESSAGES = {
+  [ResultCode.SUCCESS]: "\uC815\uC0C1",
+  [ResultCode.APPLICATION_ERROR]: "\uC5B4\uD50C\uB9AC\uCF00\uC774\uC158 \uC5D0\uB7EC",
+  [ResultCode.INVALID_REQUEST_PARAMETER]: "\uC798\uBABB\uB41C \uC694\uCCAD \uD30C\uB77C\uBBF8\uD130",
+  [ResultCode.NO_OPENAPI_SERVICE]: "\uD574\uB2F9 \uC624\uD508API \uC11C\uBE44\uC2A4 \uC5C6\uC74C",
+  [ResultCode.SERVICE_ACCESS_DENIED]: "\uC11C\uBE44\uC2A4 \uC811\uADFC \uAC70\uBD80",
+  [ResultCode.REQUEST_LIMIT_EXCEEDED]: "\uC11C\uBE44\uC2A4 \uC694\uCCAD \uC81C\uD55C \uD69F\uC218 \uCD08\uACFC",
+  [ResultCode.UNREGISTERED_SERVICE_KEY]: "\uB4F1\uB85D\uB418\uC9C0 \uC54A\uC740 \uC11C\uBE44\uC2A4\uD0A4",
+  [ResultCode.EXPIRED_SERVICE_KEY]: "\uC11C\uBE44\uC2A4\uD0A4 \uAE30\uD55C \uB9CC\uB8CC",
+  [ResultCode.UNREGISTERED_IP]: "\uB4F1\uB85D\uB418\uC9C0 \uC54A\uC740 IP",
+  [ResultCode.UNKNOWN_ERROR]: "\uAE30\uD0C0 \uC5D0\uB7EC",
+  [ResultCode.HTTP_ERROR]: "HTTP \uC5D0\uB7EC",
+  [ResultCode.SERVICE_TIMEOUT]: "\uC11C\uBE44\uC2A4 \uD0C0\uC784\uC544\uC6C3",
+  [ResultCode.GATEWAY_AUTH_ERROR]: "\uAC8C\uC774\uD2B8\uC6E8\uC774 \uC778\uC99D \uC624\uB958",
+  [ResultCode.MISSING_REQUIRED_PARAMETER]: "\uD544\uC218 \uD30C\uB77C\uBBF8\uD130 \uB204\uB77D",
+  [ResultCode.INVALID_DATA_FORMAT]: "\uC798\uBABB\uB41C dataFormat (json/xml\uB9CC \uAC00\uB2A5)",
+  [ResultCode.MAX_ROWS_EXCEEDED]: "\uCD5C\uB300 \uBAA9\uB85D \uC218 \uCD08\uACFC",
+  [ResultCode.INVALID_TOKEN]: "\uC798\uBABB\uB41C \uD1A0\uD070 \uD30C\uB77C\uBBF8\uD130",
+  [ResultCode.TOKEN_EXPIRED]: "\uD1A0\uD070 \uC720\uD6A8\uAE30\uD55C \uB9CC\uB8CC",
+  [ResultCode.FILE_NOT_FOUND]: "\uD30C\uC77C\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC74C",
+  [ResultCode.HRDK_SERVER_ERROR]: "HRDK \uC11C\uBC84 \uC5D0\uB7EC"
+};
+var GongdataError = class _GongdataError extends Error {
+  code;
+  originalResponse;
+  constructor(code, message, originalResponse) {
+    const errorMessage = message ?? RESULT_MESSAGES[code] ?? `Unknown error: ${code}`;
+    super(errorMessage);
+    this.name = "GongdataError";
+    this.code = code;
+    this.originalResponse = originalResponse;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _GongdataError);
+    }
+  }
+  static isGongdataError(error) {
+    return error instanceof _GongdataError;
+  }
+  static fromResponse(header, originalResponse) {
+    return new _GongdataError(header.resultCode, header.resultMsg, originalResponse);
+  }
+};
+
+// src/core/parser.ts
+var xmlParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  textNodeName: "#text",
+  parseTagValue: false,
+  // '00' 같은 값을 숫자로 변환하지 않음
+  trimValues: true
+});
+function parseXml(xml) {
+  return xmlParser.parse(xml);
+}
+function isXmlResponse(contentType) {
+  return contentType?.includes("application/xml") ?? contentType?.includes("text/xml") ?? false;
+}
+function validateResponse(header) {
+  const { resultCode, resultMsg } = header;
+  if (resultCode !== ResultCode.SUCCESS) {
+    throw GongdataError.fromResponse({ resultCode, resultMsg });
+  }
+}
+function normalizeXmlItems(items) {
+  if (items === "" || items === null || items === void 0) {
+    return [];
+  }
+  const { item } = items;
+  if (item === null || item === void 0) {
+    return [];
+  }
+  if (Array.isArray(item)) {
+    return item;
+  }
+  return [item];
+}
+function normalizeJsonItems(items) {
+  if (items === "" || items === null || items === void 0) {
+    return [];
+  }
+  if (Array.isArray(items)) {
+    return items;
+  }
+  return [];
+}
+function parseResponse(data, contentType) {
+  if (typeof data === "string") {
+    if (isXmlResponse(contentType)) {
+      const parsed = parseXml(data);
+      validateResponse(parsed.response.header);
+      return {
+        header: parsed.response.header,
+        body: {
+          items: normalizeXmlItems(parsed.response.body.items),
+          numOfRows: Number(parsed.response.body.numOfRows),
+          pageNo: Number(parsed.response.body.pageNo),
+          totalCount: Number(parsed.response.body.totalCount)
+        }
+      };
+    } else {
+      const parsed = JSON.parse(data);
+      validateResponse(parsed.header);
+      return {
+        header: parsed.header,
+        body: {
+          items: normalizeJsonItems(parsed.body.items),
+          numOfRows: parsed.body.numOfRows,
+          pageNo: parsed.body.pageNo,
+          totalCount: parsed.body.totalCount
+        }
+      };
+    }
+  } else {
+    const parsed = data;
+    validateResponse(parsed.header);
+    return {
+      header: parsed.header,
+      body: {
+        items: normalizeJsonItems(parsed.body.items),
+        numOfRows: parsed.body.numOfRows,
+        pageNo: parsed.body.pageNo,
+        totalCount: parsed.body.totalCount
+      }
+    };
+  }
+}
+
+// src/core/http.ts
+var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_NUM_OF_ROWS = 100;
+var HttpClient = class {
+  serviceKey;
+  timeout;
+  maxRetries;
+  retryDelay;
+  constructor(config) {
+    this.serviceKey = config.serviceKey;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = config.retry?.maxRetries ?? 3;
+    this.retryDelay = config.retry?.delay ?? 1e3;
+  }
+  /**
+   * 서비스 키 반환 (일부 API에서 직접 URL 구성 시 필요)
+   */
+  getServiceKey() {
+    return this.serviceKey;
+  }
+  /**
+   * URL 파라미터 빌드
+   */
+  buildParams(params) {
+    const searchParams = new URLSearchParams();
+    searchParams.set("serviceKey", this.serviceKey);
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) {
+        searchParams.set(key, String(value));
+      }
+    }
+    return searchParams;
+  }
+  /**
+   * 단일 요청 실행 (재시도 포함)
+   */
+  async request(baseUrl, options) {
+    const { path, params = {}, pageNo = 1, numOfRows = DEFAULT_NUM_OF_ROWS } = options;
+    const url = `${baseUrl}${path}`;
+    const searchParams = this.buildParams({
+      ...params,
+      pageNo,
+      numOfRows,
+      dataFormat: "json"
+      // 필수 파라미터
+    });
+    const fullUrl = `${url}?${searchParams.toString()}`;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(fullUrl, {
+          method: "GET",
+          signal: controller.signal,
+          headers: {
+            Accept: "application/json, application/xml"
+          }
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          throw new GongdataError(
+            ResultCode.HTTP_ERROR,
+            `HTTP ${response.status}: ${response.statusText}`
+          );
+        }
+        const contentType = response.headers.get("content-type");
+        const text = await response.text();
+        const parsed = parseResponse(text, contentType);
+        const { body } = parsed;
+        return {
+          data: body.items,
+          pagination: {
+            pageNo: body.pageNo,
+            numOfRows: body.numOfRows,
+            totalCount: body.totalCount
+          }
+        };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (lastError.name === "AbortError") {
+          lastError = new GongdataError(ResultCode.SERVICE_TIMEOUT, "Request timeout");
+        }
+        if (GongdataError.isGongdataError(lastError)) {
+          const nonRetryableCodes = [
+            ResultCode.UNREGISTERED_SERVICE_KEY,
+            ResultCode.EXPIRED_SERVICE_KEY,
+            ResultCode.SERVICE_ACCESS_DENIED,
+            ResultCode.INVALID_REQUEST_PARAMETER,
+            ResultCode.UNREGISTERED_IP,
+            ResultCode.MISSING_REQUIRED_PARAMETER,
+            ResultCode.INVALID_DATA_FORMAT
+          ];
+          if (nonRetryableCodes.includes(lastError.code)) {
+            throw lastError;
+          }
+        }
+        if (attempt < this.maxRetries) {
+          await this.sleep(this.retryDelay * (attempt + 1));
+        }
+      }
+    }
+    throw lastError ?? new GongdataError(ResultCode.APPLICATION_ERROR, "Unknown error");
+  }
+  /**
+   * 전체 페이지 데이터 수집
+   */
+  async requestAll(baseUrl, options, numOfRows = DEFAULT_NUM_OF_ROWS) {
+    const allItems = [];
+    let pageNo = 1;
+    let totalCount = 0;
+    do {
+      const result = await this.request(baseUrl, {
+        ...options,
+        pageNo,
+        numOfRows
+      });
+      allItems.push(...result.data);
+      totalCount = result.pagination.totalCount;
+      pageNo++;
+    } while (allItems.length < totalCount);
+    return allItems;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/core/response.ts
+var DataResponse = class {
+  /** 정규화된 데이터 (getter) */
+  get data() {
+    return this.getData();
+  }
+  /** 원본 데이터 (getter) */
+  get rawData() {
+    return this.getRawData();
+  }
+  /**
+   * 데이터가 비어있는지 확인
+   */
+  isEmpty() {
+    return this.data.length === 0;
+  }
+  /**
+   * 데이터 개수
+   */
+  count() {
+    return this.data.length;
+  }
+};
+var PaginatedResponse = class extends DataResponse {
+  /** 페이지네이션 정보 (getter) */
+  get pagination() {
+    return this.getPagination();
+  }
+  /** 전체 데이터 개수 */
+  get totalCount() {
+    return this.pagination.totalCount;
+  }
+  /** 현재 페이지 번호 */
+  get pageNo() {
+    return this.pagination.pageNo;
+  }
+  /** 페이지 당 항목 수 */
+  get numOfRows() {
+    return this.pagination.numOfRows;
+  }
+  /**
+   * 다음 페이지 존재 여부
+   */
+  hasNextPage() {
+    const { pageNo, numOfRows, totalCount } = this.pagination;
+    return pageNo * numOfRows < totalCount;
+  }
+};
+
+// src/services/base.ts
+var BaseService = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 단일 페이지 요청
+   */
+  async request(options) {
+    return this.http.request(this.baseUrl, options);
+  }
+  /**
+   * 전체 페이지 자동 수집
+   */
+  async requestAll(options, numOfRows) {
+    return this.http.requestAll(this.baseUrl, options, numOfRows);
+  }
+};
+
+// src/services/qualification/transformers.ts
+function formatDate(yyyymmdd) {
+  if (!yyyymmdd || yyyymmdd.length !== 8) return yyyymmdd;
+  return `${yyyymmdd.slice(0, 4)}-${yyyymmdd.slice(4, 6)}-${yyyymmdd.slice(6, 8)}`;
+}
+function transformExamSchedule(raw) {
+  const writtenExam = {
+    registrationStart: formatDate(raw.docRegStartDt),
+    registrationEnd: formatDate(raw.docRegEndDt),
+    examStart: formatDate(raw.docExamStartDt),
+    examEnd: formatDate(raw.docExamEndDt),
+    resultDate: formatDate(raw.docPassDt)
+  };
+  const practicalExam = {
+    registrationStart: formatDate(raw.pracRegStartDt),
+    registrationEnd: formatDate(raw.pracRegEndDt),
+    examStart: formatDate(raw.pracExamStartDt),
+    examEnd: formatDate(raw.pracExamEndDt),
+    resultDate: formatDate(raw.pracPassDt)
+  };
+  return {
+    year: Number(raw.implYy),
+    round: raw.implSeq,
+    category: {
+      code: raw.qualgbCd,
+      name: raw.qualgbNm
+    },
+    description: raw.description,
+    writtenExam,
+    practicalExam
+  };
+}
+function transformExamSchedules(rawList) {
+  return rawList.map(transformExamSchedule);
+}
+function transformSubject(raw) {
+  return {
+    code: raw.jmcd,
+    name: raw.jmfldnm,
+    category: {
+      code: raw.qualgbcd,
+      name: raw.qualgbnm
+    },
+    series: {
+      code: raw.seriescd,
+      name: raw.seriesnm
+    },
+    majorJobField: {
+      code: raw.obligfldcd,
+      name: raw.obligfldnm
+    },
+    minorJobField: {
+      code: raw.mdobligfldcd,
+      name: raw.mdobligfldnm
+    }
+  };
+}
+function transformSubjects(rawList) {
+  return rawList.map(transformSubject);
+}
+
+// src/services/qualification/response.ts
+var ScheduleResponse = class extends PaginatedResponse {
+  _raw;
+  _data;
+  _pagination;
+  constructor(raw, data, pagination) {
+    super();
+    this._raw = raw;
+    this._data = data;
+    this._pagination = pagination;
+  }
+  getData() {
+    return this._data;
+  }
+  getRawData() {
+    return this._raw;
+  }
+  getPagination() {
+    return this._pagination;
+  }
+};
+var AllSchedulesResponse = class extends DataResponse {
+  _raw;
+  _data;
+  constructor(raw, data) {
+    super();
+    this._raw = raw;
+    this._data = data;
+  }
+  getData() {
+    return this._data;
+  }
+  getRawData() {
+    return this._raw;
+  }
+};
+var SubjectResponse = class extends DataResponse {
+  _raw;
+  _data;
+  constructor(raw, data) {
+    super();
+    this._raw = raw;
+    this._data = data;
+  }
+  getData() {
+    return this._data;
+  }
+  getRawData() {
+    return this._raw;
+  }
+  /**
+   * 종목코드로 찾기
+   */
+  findByCode(code) {
+    return this._data.find((s) => s.code === code);
+  }
+  /**
+   * 종목명으로 찾기
+   */
+  findByName(name) {
+    return this._data.find((s) => s.name === name);
+  }
+  /**
+   * 자격구분으로 필터링
+   */
+  filterByCategory(categoryCode) {
+    return this._data.filter((s) => s.category.code === categoryCode);
+  }
+};
+
+// src/services/qualification/service.ts
+var SCHEDULE_API_BASE_URL = "http://apis.data.go.kr/B490007/qualExamSchd";
+var SUBJECT_API_BASE_URL = "http://openapi.q-net.or.kr/api/service/rest/InquiryListNationalQualifcationSVC";
+var QualificationService = class extends BaseService {
+  baseUrl = SCHEDULE_API_BASE_URL;
+  /**
+   * 시험일정 목록 조회 (단일 페이지)
+   *
+   * @example
+   * ```typescript
+   * const result = await client.qualification.getSchedules({ year: 2026 });
+   *
+   * // 정규화된 데이터 (SDK 보장)
+   * result.getData()[0].writtenExam.registrationStart  // '2026-01-24'
+   *
+   * // 원본 데이터 (공공 API 그대로)
+   * result.getRawData()[0].docRegStartDt  // '20260124'
+   * ```
+   */
+  async getSchedules(params, options) {
+    const result = await this.request({
+      path: "/getQualExamSchdList",
+      params: {
+        implYy: params.year,
+        qualgbCd: params.category,
+        jmCd: params.jmCode
+      },
+      pageNo: options?.pageNo,
+      numOfRows: options?.numOfRows
+    });
+    return new ScheduleResponse(
+      result.data,
+      transformExamSchedules(result.data),
+      result.pagination
+    );
+  }
+  /**
+   * 시험일정 전체 조회 (모든 페이지 자동 수집)
+   */
+  async getAllSchedules(params) {
+    const raw = await this.requestAll({
+      path: "/getQualExamSchdList",
+      params: {
+        implYy: params.year,
+        qualgbCd: params.category,
+        jmCd: params.jmCode
+      }
+    });
+    return new AllSchedulesResponse(raw, transformExamSchedules(raw));
+  }
+  /**
+   * 국가자격 종목 전체 목록 조회
+   *
+   * @example
+   * ```typescript
+   * const result = await client.qualification.getSubjects();
+   *
+   * // 정규화된 데이터
+   * result.getData()[0].name  // '정보처리기사'
+   *
+   * // 편의 메서드
+   * result.findByName('정보처리기사')  // Subject
+   * result.filterByCategory('T')  // 국가기술자격만
+   * ```
+   */
+  async getSubjects() {
+    const url = `${SUBJECT_API_BASE_URL}/getList?serviceKey=${this.http.getServiceKey()}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/xml" }
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const xml = await response.text();
+    const parsed = parseXml(xml);
+    validateResponse(parsed.response.header);
+    const raw = normalizeXmlItems(parsed.response.body.items);
+    return new SubjectResponse(raw, transformSubjects(raw));
+  }
+};
+
+// src/services/qualification/constants.ts
+var QualificationCategory = {
+  /** 국가기술자격 */
+  NATIONAL_TECHNICAL: "T",
+  /** 과정평가형자격 */
+  COURSE_EVALUATION: "C",
+  /** 일학습병행자격 */
+  WORK_LEARNING: "W",
+  /** 국가전문자격 */
+  NATIONAL_PROFESSIONAL: "S"
+};
+var JmCode = {
+  // === 정보통신 ===
+  /** 정보처리기사 */
+  INFORMATION_PROCESSING_ENGINEER: "1320",
+  /** 정보처리산업기사 */
+  INFORMATION_PROCESSING_INDUSTRIAL_ENGINEER: "2290",
+  /** 정보관리기술사 */
+  INFORMATION_MANAGEMENT_PROFESSIONAL_ENGINEER: "0601",
+  /** 컴퓨터시스템응용기술사 */
+  COMPUTER_SYSTEM_APPLICATION_PROFESSIONAL_ENGINEER: "0622",
+  // === 전기/전자 ===
+  /** 전기기사 */
+  ELECTRICAL_ENGINEER: "1150",
+  /** 전기기능사 */
+  ELECTRICAL_TECHNICIAN: "7780",
+  /** 전기공사기사 */
+  ELECTRICAL_CONSTRUCTION_ENGINEER: "1160",
+  /** 전자기사 */
+  ELECTRONICS_ENGINEER: "1230",
+  // === 기계 ===
+  /** 기계기사 */
+  MECHANICAL_ENGINEER: "1431",
+  /** 용접기사 */
+  WELDING_ENGINEER: "1022",
+  /** 지게차운전기능사 */
+  FORKLIFT_DRIVER_TECHNICIAN: "7875",
+  // === 건설 ===
+  /** 건축기사 */
+  ARCHITECTURE_ENGINEER: "1190",
+  /** 토목기사 */
+  CIVIL_ENGINEERING_ENGINEER: "1080",
+  // === 조리/서비스 ===
+  /** 한식조리기능사 */
+  KOREAN_CUISINE_TECHNICIAN: "7910",
+  /** 양식조리기능사 */
+  WESTERN_CUISINE_TECHNICIAN: "7911",
+  /** 미용사(일반) */
+  BEAUTICIAN_GENERAL: "7937"
+};
+
+// src/client.ts
+function createClient(config) {
+  const http = new HttpClient(config);
+  return {
+    qualification: new QualificationService(http)
+  };
+}
+
+export { AllSchedulesResponse, BaseService, DataResponse, GongdataError, JmCode, PaginatedResponse, QualificationCategory, QualificationService, ResultCode, ScheduleResponse, SubjectResponse, createClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map