@bluessu/meal-scraper 0.1.0

package/LICENSE

@@ -0,0 +1,46 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2026 food-crawling-library contributors
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+  software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+  to take away your freedom to share and change the works. By contrast,
+  the GNU General Public License is intended to guarantee your freedom to
+  share and change all versions of a program--to make sure it remains free
+  software for all its users. We, the Free Software Foundation, use the
+  GNU General Public License for most of our software; it applies to
+a large part of the GNU operating system and to many other software systems
+  and works.
+
+  When we speak of free software, we are referring to freedom, not
+  price. Our General Public Licenses are designed to make sure that you
+  have the freedom to distribute copies of free software (and charge for
+  that service if you wish), that you receive source code or can get it
+  if you want it, that you can change the software or use pieces of it
+  in new free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+  these rights or asking you to surrender them. This is accomplished by
+  making requirements that forbid you to deny others these rights or to
+  ask them to surrender theirs.
+
+  For example, if you distribute copies of such a program, whether gratis
+  or for a fee, you must give the recipients all the rights that you
+  have received. You must make sure that they, too, receive or can get the
+  source code. And you must show them these terms so they know their rights.
+
+  Developers who use our licenses protect your rights in two ways: (1)
+  by clearly stating that there is no warranty for this free software. For
+  both users and authors to understand that there is no warranty; (2) by
+  making sure that modified versions of the software remain free.
+
+  For the full legal text and complete terms, use the official GNU license
+  text.

package/README.md

@@ -0,0 +1,210 @@
+# @bluessu/meal-scraper
+
+[![npm version](https://img.shields.io/npm/v/@bluessu/meal-scraper.svg)](https://www.npmjs.com/package/@bluessu/meal-scraper)
+[![npm downloads](https://img.shields.io/npm/dm/@bluessu/meal-scraper.svg)](https://www.npmjs.com/package/@bluessu/meal-scraper)
+[![license](https://img.shields.io/npm/l/@bluessu/meal-scraper.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/language-TypeScript-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+## WIP (Working In Progress)
+
+현재 이 라이브러리는 개발 중인 상태입니다.
+
+## 프로젝트 출처
+
+이 프로젝트의 초기 구현은 [EAT-SSU/Food-Crawling](https://github.com/EAT-SSU/Food-Crawling) 내부 구현을 바탕으로 작성되었습니다.
+
+## 지원 환경
+
+- Node.js: `>= 18`
+- 공개 라이선스: GPL-3.0
+- OpenAI 파서를 사용하려면 프로젝트에 `openai`가 별도 설치되어 있어야 합니다. (`openai`는 선택 의존성입니다)
+
+## 배포/릴리스
+
+패키지 배포는 다음 스크립트를 사용합니다.
+
+```bash
+pnpm run release:patch
+pnpm run release:minor
+pnpm run release:major
+```
+
+## 설치
+
+Using npm:
+
+```bash
+npm i @bluessu/meal-scraper
+```
+
+GPT 파서를 사용하려면 먼저 OpenAI 클라이언트를 설치하세요.
+
+```bash
+pnpm add openai
+```
+
+Using yarn
+
+```bash
+yarn add @bluessu/meal-scraper
+```
+
+Using pnpm:
+
+```bash
+pnpm add @bluessu/meal-scraper
+```
+
+## 특징
+
+- `createMealClient()` 또는 `new MealClient()`로 클라이언트 생성
+- 단건 조회/배치 조회/범위 조회 지원
+- 날짜 입력을 `string` 또는 `Date`로 유연하게 지원
+- 내부 구현 분리로 공개 API가 간결하고 유지보수하기 쉬운 구조
+
+## 공개 API
+
+`src/index.ts`에서 노출되는 주요 API는 다음과 같습니다.
+
+- `MealClient`
+- `createMealClient`
+- `normalizeMenuDate`
+- `buildDateRange`
+- 타입
+  - `MenuDateInput`
+  - `MenuDate`
+  - `ParserMode`
+  - `MealClientOptions`
+  - `RangeOptions`
+- 도메인/설정
+  - `CafeteriaType`
+  - `RawMenuData`
+  - `DailyMenu`
+  - `FoodCrawlerSettings`
+  - `defaultSettings`
+- 예외
+  - `BaseCafeteriaException`
+  - `HolidayException`
+  - `MenuFetchException`
+  - `MenuParseException`
+
+## 기본 사용법
+
+```ts
+import {
+  MealClient,
+  createMealClient,
+  CafeteriaType,
+  normalizeMenuDate,
+  buildDateRange,
+} from "@bluessu/meal-scraper";
+
+const client = createMealClient();
+await client.getRawMenu(CafeteriaType.DODAM, new Date());
+await client.getDailyMenu(CafeteriaType.HAKSIK, "2026-02-28");
+await client.getDailyMenusByRange(CafeteriaType.FACULTY, "2026-02-28", "2026-03-02", {
+  concurrency: 3,
+});
+```
+
+## Client 옵션
+
+```ts
+export type ParserMode = "noop" | "gpt" | "custom";
+```
+
+- `noop`(기본): 기본 파서(`NoopMenuParser`) 사용
+- `gpt`: OpenAI 파서 사용 (`gptApiKey` 필수)
+- `custom`: 직접 구현한 파서를 `parserImpl`로 주입
+
+```ts
+import { createMealClient } from "@bluessu/meal-scraper";
+
+// GPT 모드 예시 (키가 없으면 생성 단계에서 에러)
+const gptClient = createMealClient({
+  parser: "gpt",
+  gptApiKey: process.env.OPENAI_API_KEY,
+});
+
+// 커스텀 파서 주입 예시
+const customClient = createMealClient({
+  parser: "custom",
+  parserImpl: {
+    parseMenu: async (raw) => {
+      // 사용자 구현
+      return {
+        date: raw.date,
+        cafeteria: raw.cafeteria,
+        status: "open",
+        breakfast: {},
+        lunch: {},
+        dinner: {},
+      };
+    },
+  },
+});
+```
+
+## 날짜 정규화 유틸
+
+```ts
+import { normalizeMenuDate, buildDateRange } from "@bluessu/meal-scraper";
+
+normalizeMenuDate("2026-02-28"); // "2026-02-28"
+normalizeMenuDate(new Date(2026, 1, 28)); // "2026-02-28"
+
+buildDateRange("2026-02-28", "2026-03-02"); // ["2026-02-28","2026-03-01","2026-03-02"]
+```
+
+지원 날짜 포맷은 내부적으로 모두 `YYYY-MM-DD`로 정규화됩니다.
+
+## API 목록
+
+### `MealClient`
+
+- `getRawMenu(cafeteria, date): Promise<RawMenuData>`
+- `getDailyMenu(cafeteria, date): Promise<DailyMenu>`
+- `getRawMenus(cafeteria, dates, options?): Promise<RawMenuData[]>`
+- `getDailyMenus(cafeteria, dates, options?): Promise<DailyMenu[]>`
+- `getRawMenusByRange(cafeteria, start, end, options?): Promise<RawMenuData[]>`
+- `getDailyMenusByRange(cafeteria, start, end, options?): Promise<DailyMenu[]>`
+
+### 옵션
+
+- `RangeOptions`
+  - `startInclusive?: boolean` (기본값: `true`)
+  - `concurrency?: number` (기본값: `3`)
+
+## 에러 처리
+
+```ts
+import { HolidayException, MenuFetchException } from "@bluessu/meal-scraper";
+
+try {
+  const menu = await client.getDailyMenu(CafeteriaType.DORMITORY, "2026-02-28");
+} catch (error) {
+  if (error instanceof HolidayException) {
+    console.log("휴일입니다");
+  } else if (error instanceof MenuFetchException) {
+    console.log("수집 실패");
+  } else {
+    console.error(error);
+  }
+}
+```
+
+## 프로젝트 구조
+
+현재 공개 엔트리는 `src/index.ts`에 집중하고, 실제 구현은 내부 레이어로 분리되어 있습니다.
+
+- `src/index.ts`: 라이브러리 바렐(export hub)
+- `src/client/*`: 클라이언트 API 및 유틸
+- `src/services/*`: 수집/파싱 오케스트레이션
+- `src/repositories/*`: 사이트별 스크래퍼
+- `src/parsers/*`: 파싱 전략
+- `src/domain.ts`, `src/config.ts`, `src/errors.ts`: 도메인/설정/예외
+
+## 라이선스
+
+GNU General Public License Version 3 (GPL-3.0) 입니다.  
+라이선스 파일은 `LICENSE`를 확인하세요.