pal-crawl 1.6.0 → 1.7.0

package/README.md

@@ -20,9 +20,15 @@
 - [Configuration](#configuration)
 - [Base Types](#base-types)
 - [Methods](#methods)
-  - [get](#get)
-  - [getContentHTML](#getcontenthtml--promisestring)
+  - [get](#get--promiseitable-data)
+  - [getContentHTML](#getcontenthtmlid-string--promisestring)
   - [getContent](#getcontentid-string--promiseicontentdata)
+  - [getDone](#getdone--promiseitable-data)
+  - [getDoneContentHTML](#getdonecontenthtmlid-string--promisestring)
+  - [getDoneContent](#getdonecontentid-string--promiseicontentdata)
+  - [search / searchDone](#searchquery-isearchquery--promiseisearchresult)
+  - [getPage / getDonePage](#getpagepageindex-number-pageunit-number--promiseitable-data)
+  - [getAllPages / getAllDonePages](#getallpagesquery-isearchquery-options-ibulkoptions--asyncgeneratorisearchresult)
 - [Examples](#examples)
 - [License](#license)
 
@@ -119,11 +125,57 @@ interface IContentData {
 }
 ```
 
+`ISearchResult`는 검색/페이지 조회 결과를 나타내는 인터페이스입니다.
+
+```typescript
+interface ISearchResult {
+  total: number; // 전체 건수
+  totalPages: number; // 전체 페이지 수
+  currentPage: number; // 현재 페이지
+  items: ITableData[]; // 현재 페이지 항목 목록
+}
+```
+
+`ISearchQuery`는 검색 필터 옵션을 나타내는 인터페이스입니다.
+
+```typescript
+interface ISearchQuery {
+  pageIndex?: number; // 페이지 번호 (기본값: 1)
+  pageUnit?: number; // 페이지당 항목 수 (5~9, 20, 30, 50, 100; 기본값: 10)
+  committeeId?: string; // 소관위원회 ID (예: '9700006' = 법제사법위원회)
+  billName?: string; // 법안명 검색어
+  represent?: string; // 대표발의자 검색어
+  proposers?: string; // 공동발의자 검색어 (쉼표 구분 AND 조건)
+  ppslRsonMnCn?: string; // 제안이유 검색어
+  sortCol?:
+    | 'BILL_NO'
+    | 'BILL_NAME'
+    | 'CURR_COMMITTEE'
+    | 'OPN_CNT'
+    | 'LGSLT_PA_RG_DT';
+  sortGbn?: 'DESC' | 'ASC';
+  // 종료된 입법예고 전용:
+  fromAge?: number; // 시작 대수 (예: 21)
+  toAge?: number; // 종료 대수 (예: 22)
+  billNo?: string; // 의안번호 검색어
+}
+```
+
+`IBulkOptions`는 대량 수집 시 동작을 제어하는 인터페이스입니다.
+
+```typescript
+interface IBulkOptions {
+  delayMs?: number; // 페이지 간 요청 지연 (밀리초, 기본값: 500)
+  concurrency?: number; // 동시 요청 수 (기본값: 1)
+  maxPages?: number; // 최대 수집 페이지 수 (기본값: 전체)
+}
+```
+
 ---
 
 ## Methods
 
-### get() => Promise<ITableData[]>
+### get() => Promise\<ITableData[]>
 
 `get` 메서드는 진행 중인 입법 예고 데이터를 가져옵니다.
 
@@ -140,7 +192,7 @@ console.log(table);
 
 ### getContentHTML(id: string) => Promise\<string>
 
-`getContentHTML` 메서드는 특정 의안 ID의 본문 페이지 HTML 원문을 가져옵니다.
+`getContentHTML` 메서드는 진행 중인 입법 예고 중 특정 의안 ID의 본문 페이지 HTML 원문을 가져옵니다.
 
 ```typescript
 import { PalCrawl } from 'pal-crawl';
@@ -179,6 +231,171 @@ console.log(content);
 // }
 ```
 
+### getDone() => Promise\<ITableData[]>
+
+`getDone` 메서드는 종료된 입법 예고 데이터를 가져옵니다.
+
+반환되는 각 항목에는 `contentId`가 포함되며, 이 값을 `getDoneContentHTML` 또는 `getDoneContent`에 전달해 본문 조회를 바로 수행할 수 있습니다.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+const table = await palCrawl.getDone();
+
+console.log(table);
+```
+
+### getDoneContentHTML(id: string) => Promise\<string>
+
+`getDoneContentHTML` 메서드는 종료된 입법 예고 중 특정 의안 ID의 본문 페이지 HTML 원문을 가져옵니다.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+const table = await palCrawl.getDone();
+
+const id = table[0]?.contentId;
+if (id) {
+  const contentHtml = await palCrawl.getDoneContentHTML(id);
+  console.log(contentHtml);
+}
+```
+
+### getDoneContent(id: string) => Promise\<IContentData>
+
+`getDoneContent` 메서드는 종료된 입법 예고 중 특정 의안 ID의 본문 페이지를 파싱해 JSON 객체(`IContentData`)로 반환합니다.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+const content = await palCrawl.getDoneContent(
+  'PRC_S2R6N0M3K2J3K1J5K3S8R3P4O3P5X6',
+);
+
+console.log(content);
+// {
+//   title: '[2218503] 전자장치 부착 등에 관한 법률 일부개정법률안 (김기현의원 등 10인)',
+//   proposalReason: '...',
+//   billNumber: '2218503',
+//   proposer: '김기현의원 등 10인',
+//   ...
+// }
+```
+
+---
+
+### search(query?: ISearchQuery) => Promise\<ISearchResult>
+
+`search` 메서드는 진행 중인 입법 예고를 조건에 맞게 검색합니다. 검색 결과에는 총 건수, 페이지 정보, 항목 목록이 포함됩니다.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+
+// 기본 조회 (1페이지 10건)
+const result = await palCrawl.search();
+console.log(result.total, result.totalPages, result.items);
+
+// 법안명 필터 + 정렬
+const filtered = await palCrawl.search({
+  billName: '도로교통법',
+  sortCol: 'BILL_NAME',
+  sortGbn: 'ASC',
+  pageUnit: 20,
+});
+```
+
+### searchDone(query?: ISearchQuery) => Promise\<ISearchResult>
+
+`searchDone` 메서드는 종료된 입법 예고를 조건에 맞게 검색합니다. `fromAge`, `toAge`, `billNo` 필터를 추가로 지원합니다.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+
+// 22대 종료 입법예고만 조회
+const result = await palCrawl.searchDone({ fromAge: 22, toAge: 22 });
+console.log(result.total, result.items);
+```
+
+---
+
+### getPage(pageIndex: number, pageUnit?: number) => Promise\<ITableData[]>
+
+`getPage` 메서드는 진행 중인 입법 예고에서 특정 페이지의 항목을 가져옵니다.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+
+const page1 = await palCrawl.getPage(1); // 1페이지 (기본 10건)
+const page2 = await palCrawl.getPage(2, 20); // 2페이지, 20건씩
+```
+
+### getDonePage(pageIndex: number, pageUnit?: number) => Promise\<ITableData[]>
+
+`getDonePage` 메서드는 종료된 입법 예고에서 특정 페이지의 항목을 가져옵니다.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+const page3 = await palCrawl.getDonePage(3);
+```
+
+---
+
+### getAllPages(query?: ISearchQuery, options?: IBulkOptions) => AsyncGenerator\<ISearchResult>
+
+`getAllPages` 메서드는 진행 중인 입법 예고를 여러 페이지에 걸쳐 순차적으로 수집하는 비동기 제너레이터입니다. `for await...of` 루프로 한 페이지씩 처리할 수 있습니다.
+
+- `delayMs` (기본값: 500): 페이지 요청 사이의 지연 시간(ms). 서버 부하를 줄이기 위해 설정하세요.
+- `concurrency` (기본값: 1): 동시에 요청할 페이지 수.
+- `maxPages` (기본값: 전체 페이지): 수집할 최대 페이지 수.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+
+// 처음 5 페이지를 순서대로 수집
+for await (const page of palCrawl.getAllPages(
+  {},
+  { maxPages: 5, delayMs: 300 },
+)) {
+  console.log(
+    `페이지 ${page.currentPage}/${page.totalPages}: ${page.items.length}건`,
+  );
+  for (const item of page.items) {
+    console.log(item.subject);
+  }
+}
+```
+
+### getAllDonePages(query?: ISearchQuery, options?: IBulkOptions) => AsyncGenerator\<ISearchResult>
+
+`getAllDonePages`는 종료된 입법 예고에 대한 대량 수집 제너레이터입니다.
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+
+// 22대 종료 입법예고 전체 수집 (concurrency=2, 지연 200ms)
+for await (const page of palCrawl.getAllDonePages(
+  { fromAge: 22, toAge: 22 },
+  { concurrency: 2, delayMs: 200 },
+)) {
+  console.log(`${page.currentPage}/${page.totalPages}: ${page.items.length}건`);
+}
+```
+
 ---
 
 ## Examples
@@ -243,6 +460,78 @@ const palCrawl = new PalCrawl(config);
 const data = await palCrawl.get();
 ```
 
+### 종료된 입법예고 목록에서 본문 가져오기
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+const table = await palCrawl.getDone();
+
+const first = table.find((item) => item.contentId);
+if (first?.contentId) {
+  const content = await palCrawl.getDoneContent(first.contentId);
+  console.log(content.title);
+  console.log(content.proposalReason);
+  console.log(content.billNumber);
+  console.log(content.noticePeriod);
+}
+```
+
+### 검색 필터를 사용해 법안 조회하기
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+
+// 법안명 검색
+const result = await palCrawl.search({ billName: '도로교통법', pageUnit: 20 });
+console.log(`총 ${result.total}건 (${result.totalPages}페이지)`);
+result.items.forEach((item) => console.log(item.subject));
+
+// 22대 종료 입법예고에서 의안번호로 검색
+const done = await palCrawl.searchDone({
+  fromAge: 22,
+  toAge: 22,
+  billNo: '2218',
+});
+done.items.forEach((item) => console.log(item.subject));
+```
+
+### 대량 수집 (getAllPages / getAllDonePages)
+
+```typescript
+import { PalCrawl, type ITableData } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+const allItems: ITableData[] = [];
+
+// 진행 중인 입법예고 전체 페이지 수집 (500ms 지연)
+for await (const page of palCrawl.getAllPages({}, { delayMs: 500 })) {
+  allItems.push(...page.items);
+  console.log(`수집 중: ${page.currentPage}/${page.totalPages} 페이지`);
+}
+
+console.log(`전체 ${allItems.length}건 수집 완료`);
+```
+
+```typescript
+import { PalCrawl } from 'pal-crawl';
+
+const palCrawl = new PalCrawl();
+
+// 처음 10 페이지만, 동시 2개 요청으로 빠르게 수집
+for await (const page of palCrawl.getAllDonePages(
+  { sortCol: 'LGSLT_PA_RG_DT', sortGbn: 'DESC' },
+  { maxPages: 10, concurrency: 2, delayMs: 200 },
+)) {
+  console.log(
+    `페이지 ${page.currentPage}: ${page.items.map((i) => i.subject).join(', ')}`,
+  );
+}
+```
+
 ### 에러 처리
 
 ```typescript

package/dist/config.d.ts

@@ -2,5 +2,7 @@ export declare enum Config {
     DOMAIN = "https://pal.assembly.go.kr",
     LIST_URL = "/napal/lgsltpa/lgsltpaOngoing/list.do",
     CONTENT_URL = "/napal/lgsltpa/lgsltpaOngoing/view.do",
+    DONE_LIST_URL = "/napal/lgsltpa/lgsltpaDone/list.do",
+    DONE_CONTENT_URL = "/napal/lgsltpa/lgsltpaDone/view.do",
     UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
 }

package/dist/config.js

@@ -6,6 +6,8 @@ var Config;
     Config["DOMAIN"] = "https://pal.assembly.go.kr";
     Config["LIST_URL"] = "/napal/lgsltpa/lgsltpaOngoing/list.do";
     Config["CONTENT_URL"] = "/napal/lgsltpa/lgsltpaOngoing/view.do";
+    Config["DONE_LIST_URL"] = "/napal/lgsltpa/lgsltpaDone/list.do";
+    Config["DONE_CONTENT_URL"] = "/napal/lgsltpa/lgsltpaDone/view.do";
     Config["UserAgent"] = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
 })(Config || (exports.Config = Config = {}));
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AAAA,IAAY,MAKX;AALD,WAAY,MAAM;IAChB,+CAAqC,CAAA;IACrC,4DAAkD,CAAA;IAClD,+DAAqD,CAAA;IACrD,uIAA6H,CAAA;AAC/H,CAAC,EALW,MAAM,sBAAN,MAAM,QAKjB"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AAAA,IAAY,MAOX;AAPD,WAAY,MAAM;IAChB,+CAAqC,CAAA;IACrC,4DAAkD,CAAA;IAClD,+DAAqD,CAAA;IACrD,8DAAoD,CAAA;IACpD,iEAAuD,CAAA;IACvD,uIAA6H,CAAA;AAC/H,CAAC,EAPW,MAAM,sBAAN,MAAM,QAOjB"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { PalCrawl, type ITableData, type IAttachment, type IContentData, type PalCrawlConfig, } from './pal';
+export { PalCrawl, type ITableData, type IAttachment, type IContentData, type ISearchResult, type ISearchQuery, type IBulkOptions, type PalCrawlConfig, } from './pal';
+export { PalParser } from './parser';
 export { Config } from './config';

package/dist/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Config = exports.PalCrawl = void 0;
+exports.Config = exports.PalParser = exports.PalCrawl = void 0;
 var pal_1 = require("./pal");
 Object.defineProperty(exports, "PalCrawl", { enumerable: true, get: function () { return pal_1.PalCrawl; } });
+var parser_1 = require("./parser");
+Object.defineProperty(exports, "PalParser", { enumerable: true, get: function () { return parser_1.PalParser; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return config_1.Config; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6BAMe;AALb,+FAAA,QAAQ,OAAA;AAMV,mCAAkC;AAAzB,gGAAA,MAAM,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6BASe;AARb,+FAAA,QAAQ,OAAA;AASV,mCAAqC;AAA5B,mGAAA,SAAS,OAAA;AAClB,mCAAkC;AAAzB,gGAAA,MAAM,OAAA"}

package/dist/pal.d.ts

@@ -1,45 +1,62 @@
+import { type ITableData, type IContentData, type ISearchResult } from './parser';
+export type { IAttachment, ITableData, IContentData, ISearchResult, } from './parser';
 export interface PalCrawlConfig {
     userAgent?: string;
     timeout?: number;
     retryCount?: number;
     customHeaders?: Record<string, string>;
 }
-export interface IAttachment {
-    pdfFile: string | null;
-    hwpFile: string | null;
+export interface ISearchQuery {
+    pageIndex?: number;
+    pageUnit?: number;
+    committeeId?: string;
+    billName?: string;
+    represent?: string;
+    proposers?: string;
+    ppslRsonMnCn?: string;
+    sortCol?: 'BILL_NO' | 'BILL_NAME' | 'CURR_COMMITTEE' | 'OPN_CNT' | 'LGSLT_PA_RG_DT';
+    sortGbn?: 'DESC' | 'ASC';
+    fromAge?: number;
+    toAge?: number;
+    billNo?: string;
 }
-export interface ITableData {
-    num: number;
-    subject: string;
-    proposerCategory: string;
-    committee: string;
-    numComments: number;
-    link: string;
-    contentId: string | null;
-    attachments: IAttachment;
-}
-export interface IContentData {
-    title: string;
-    proposalReason: string | null;
-    billNumber: string | null;
-    proposer: string | null;
-    proposalDate: string | null;
-    committee: string | null;
-    referralDate: string | null;
-    noticePeriod: string | null;
-    proposalSession: string | null;
+export interface IBulkOptions {
+    delayMs?: number;
+    concurrency?: number;
+    maxPages?: number;
 }
 export declare class PalCrawl {
     private readonly httpClient;
+    private readonly parser;
     constructor(config?: PalCrawlConfig);
+    private buildListUrl;
     getPalHTML(): Promise<string>;
-    private extractContentId;
     parseTable(html: string): ITableData[];
-    private normalizeText;
-    private extractTableCellText;
-    private parseBillInfoTable;
     parseContent(html: string): IContentData;
     get(): Promise<ITableData[]>;
     getContentHTML(id: string): Promise<string>;
     getContent(id: string): Promise<IContentData>;
+    getDoneHTML(): Promise<string>;
+    getDone(): Promise<ITableData[]>;
+    getDoneContentHTML(id: string): Promise<string>;
+    getDoneContent(id: string): Promise<IContentData>;
+    /** Fetch ongoing notices with optional filters and return parsed result with metadata. */
+    search(query?: ISearchQuery): Promise<ISearchResult>;
+    /** Fetch done notices with optional filters and return parsed result with metadata. */
+    searchDone(query?: ISearchQuery): Promise<ISearchResult>;
+    /** Fetch a specific page of ongoing notices. */
+    getPage(pageIndex: number, pageUnit?: number): Promise<ITableData[]>;
+    /** Fetch a specific page of done notices. */
+    getDonePage(pageIndex: number, pageUnit?: number): Promise<ITableData[]>;
+    private _getAllPagesImpl;
+    /**
+     * Async generator that yields every page of ongoing notices.
+     * Respects `IBulkOptions` for rate-limiting and concurrency.
+     */
+    getAllPages(query?: Omit<ISearchQuery, 'pageIndex'>, options?: IBulkOptions): AsyncGenerator<ISearchResult>;
+    /**
+     * Async generator that yields every page of done notices.
+     * Respects `IBulkOptions` for rate-limiting and concurrency.
+     */
+    getAllDonePages(query?: Omit<ISearchQuery, 'pageIndex'>, options?: IBulkOptions): AsyncGenerator<ISearchResult>;
 }