@rscc/common-react 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,7 @@
 # @rscc/common-react
 
-RSCC 공통 React 훅 — `useDebounce`, `useSse`. [@rscc/common-core](https://www.npmjs.com/package/@rscc/common-core) 의 SSE 파서(`readSseStream`)를 React 상태로 래핑한다.
+RSCC 공통 React 훅 — `useDebounce`, `useSse`, `useSseEvents`. [@rscc/common-core](https://www.npmjs.com/package/@rscc/common-core) 의
+SSE 리더(채팅 프로필 `readSseStream`/`readSseChatEvents`, 범용 표준 `readSseEvents`)를 React 상태로 래핑한다.
 
 ## 설치
 
@@ -17,10 +18,12 @@ npm i @rscc/common-react
 | 훅 | 시그니처 | 설명 |
 |---|---|---|
 | `useDebounce` | `useDebounce<T>(value, delayMs = 200): T` | 마지막 안정 값만 통과 — 자동완성 API 호출 절감 |
-| `useSse` | `useSse(options?)` → `{ start, cancel, text, sources, conversationId, error, isStreaming, finishReason }` | SSE 구독 상태 훅 — 언마운트 시 자동 중단, `finishReason` 으로 종료 사유 구분, opt-in `reconnect`, 쿠키 인증 모드용 `credentials`·`csrf` |
+| `useSse` | `useSse(options?)` → `{ start, cancel, text, sources, conversationId, error, isStreaming, finishReason }` | 채팅 SSE 구독 상태 훅 — 언마운트 시 자동 중단, `finishReason` 으로 종료 사유 구분, opt-in `reconnect`, 쿠키 인증 모드용 `credentials`·`csrf`, `parser: "standard"` 로 표준 파서 어댑터 선택 |
+| `useSseEvents` | `useSseEvents(options?)` → `{ start, cancel, lastEvent, lastEventId, error, isStreaming, finishReason }` | 범용 SSE 구독 훅 (WHATWG `event`/`id`/`retry`) — `onEvent` 콜백 + `lastEvent` 1개만 상태 보관, `isTerminal` 종료 판정, opt-in `reconnect`(`Last-Event-ID` 이어받기·서버 `retry:` 존중) |
 
 `UseSseOptions`: `fetchImpl?` · `reconnect?: SseReconnectOptions` · `credentials?: RequestCredentials` · `csrf?: boolean | CsrfOptions`
-(`CsrfOptions` 는 `@rscc/common-core` 에서 export).
+· `parser?: "legacy" | "standard"` (기본 `"legacy"`). `UseSseEventsOptions`: `fetchImpl?` · `onEvent?(e)` · `isTerminal?(e)` ·
+`reconnect?` · `credentials?` · `csrf?` (`CsrfOptions`·`SseEvent` 는 `@rscc/common-core` 에서 export).
 
 ## 사용 예시
 
@@ -68,9 +71,48 @@ const sse = useSse({ reconnect: { retries: 3, minDelayMs: 1000, maxDelayMs: 1500
 - 재연결 트리거는 **"스트림 시작(`res.ok`) 후 `[DONE]` 없이 끊긴 경우"뿐** — `'done'`/`'aborted'`/
   구독 전 실패(`!res.ok`)/in-band error 프레임 종료는 서버 의도로 보고 재연결하지 않는다.
 - 각 시도는 **전체 재요청**이며 직전 시도의 `text`/`sources`/`conversationId`/`error` 를 초기화한다
-  (중복 누적 방지). 이어받기(Last-Event-ID)는 지원하지 않는다.
+  (중복 누적 방지). 이어받기(Last-Event-ID)는 지원하지 않는다 — 범용 `useSseEvents` 는 지원한다.
 - [주의] 비멱등 POST 스트림은 전체 재요청이 서버 측 중복 생성으로 이어질 수 있으므로 멱등성이 보장될 때만 켤 것.
 
+### useSse — 표준 파서 어댑터 (`parser: "standard"`)
+
+```ts
+const sse = useSse({ parser: "standard" }); // core readSseChatEvents 사용
+```
+
+- 기본 `"legacy"`(core `readSseStream`)는 현행 그대로 — 프레임 구분자 LF(`\n\n`) 고정, 첫 `data:` 라인만 읽는다.
+- `"standard"` 는 WHATWG 표준 파서 위의 채팅 어댑터 — **CRLF·CR 줄 끝**, **멀티라인 `data`**, `[DONE]` 앞뒤 공백을
+  받아들인다. 개행을 CRLF 로 정규화하는 프록시 뒤라면 이 모드를 쓴다. 콜백·`finishReason`·재연결 시맨틱과 EOF 잔여 프레임
+  처리는 레거시와 같다.
+
+### useSseEvents — 범용 SSE (알림·진행률·로그 등)
+
+```ts
+import { useSseEvents } from "@rscc/common-react";
+import type { SseEvent } from "@rscc/common-core";
+
+const { start, cancel, lastEvent, lastEventId, error, isStreaming, finishReason } = useSseEvents({
+  onEvent: (e: SseEvent) => appendLog(e),          // 누적은 소비 측에서 — 훅은 lastEvent 1개만 보관
+  isTerminal: (e) => e.event === "end",            // true → 연결 종료 + finishReason 'done'
+  reconnect: { retries: 5, minDelayMs: 1000 },     // opt-in — 기본 off
+});
+
+await start("/api/v1/jobs/42/events");
+// lastEvent: { event: "progress", data: "60", id: "17" } — 마지막 이벤트
+// lastEventId: 재연결 시 Last-Event-ID 로 실리는 값
+```
+
+- `finishReason`: `'done'`(`isTerminal` 이벤트 또는 HTTP 204) / `'aborted'`(`cancel()`·재시작·언마운트) /
+  `'interrupted'`(종료 이벤트 없이 EOF·전송 오류·구독 전 실패·재연결 소진). `isTerminal` 이 없으면 모든 종료가 EOF 라 `'interrupted'`.
+- **재연결**(opt-in)은 "스트림 시작 후 종료 이벤트 없이 끊김"에서만 — 전체 재요청이 아니라 **이어받기**다:
+  마지막 이벤트 ID 가 있으면 `Last-Event-ID` 헤더를 싣고(`init.headers` 와 병합), 서버가 `retry:` 를 보냈으면
+  계산된 백오프 대신 그 값(ms)을 대기로 쓴다. ID 는 연결을 넘어 유지된다(id 없는 이벤트도 이어받음 — EventSource 동일).
+  재연결 시 `lastEvent`/`lastEventId` 는 유지하고 `error` 만 초기화한다.
+- 구독 전 실패(`!res.ok`)는 봉투 `message` 를 `error` 로 노출하고 재연결하지 않는다. HTTP 204 는 "더 없음"으로 보고 `'done'`.
+- `onEvent`/`isTerminal` 은 이벤트 시점의 **최신 콜백**을 쓰므로 인라인 함수여도 `start` 참조가 바뀌지 않는다.
+  콜백이 throw 하면 스트림을 멈추고 `error` 로 노출하며 재연결하지 않는다.
+- `credentials`·`csrf` 는 `useSse` 와 같은 규칙 (아래 쿠키 인증 모드 참조). 언마운트 시 진행 중 스트림을 중단한다(StrictMode 안전).
+
 ### useSse — 쿠키 인증 모드 (credentials / CSRF)
 
 서버가 인증 자격을 HttpOnly 쿠키(`jwt-cookie`) 또는 서버 세션(`session`)으로 받는다면 `credentials` 와 `csrf` 를 켠다.
@@ -101,5 +143,5 @@ const sse2 = useSse({
 
 ## 관련 패키지
 
-- 코어(SSE 파서 `readSseStream`·apiClient 등): [@rscc/common-core](https://www.npmjs.com/package/@rscc/common-core)
+- 코어(SSE `readSseStream`·`readSseChatEvents`·`readSseEvents`·apiClient 등): [@rscc/common-core](https://www.npmjs.com/package/@rscc/common-core)
 - 라이선스: MIT

package/dist/index.cjs

@@ -21,7 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   useDebounce: () => useDebounce,
-  useSse: () => useSse
+  useSse: () => useSse,
+  useSseEvents: () => useSseEvents
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -41,7 +42,7 @@ var import_react2 = require("react");
 var import_common_core = require("@rscc/common-core");
 var RECONNECT_MARKER = new Error("rscc-sse-reconnect");
 function useSse(options = {}) {
-  const { fetchImpl, reconnect, credentials, csrf } = options;
+  const { fetchImpl, reconnect, credentials, csrf, parser = "legacy" } = options;
   const [text, setText] = (0, import_react2.useState)("");
   const [sources, setSources] = (0, import_react2.useState)(null);
   const [conversationId, setConversationId] = (0, import_react2.useState)(null);
@@ -97,7 +98,8 @@ function useSse(options = {}) {
             return;
           }
           streamStarted = true;
-          await (0, import_common_core.readSseStream)(res, {
+          const readChat = parser === "standard" ? import_common_core.readSseChatEvents : import_common_core.readSseStream;
+          await readChat(res, {
             onConversationId: setConversationId,
             onSources: setSources,
             onDelta: (d) => setText((prev) => prev + d),
@@ -156,13 +158,168 @@ function useSse(options = {}) {
         }
       }
     },
-    [fetchImpl, reconnect, credentials, csrf]
+    [fetchImpl, reconnect, credentials, csrf, parser]
   );
   (0, import_react2.useEffect)(() => () => abortRef.current?.abort(), []);
   return { start, cancel, text, sources, conversationId, error, isStreaming, finishReason };
 }
+
+// src/useSseEvents.ts
+var import_react3 = require("react");
+var import_common_core2 = require("@rscc/common-core");
+var RECONNECT_MARKER2 = new Error("rscc-sse-events-reconnect");
+var LAST_EVENT_ID_HEADER = "Last-Event-ID";
+var messageOf = (err) => err instanceof Error ? err.message : String(err);
+function useSseEvents(options = {}) {
+  const [lastEvent, setLastEvent] = (0, import_react3.useState)(null);
+  const [lastEventId, setLastEventId] = (0, import_react3.useState)("");
+  const [error, setError] = (0, import_react3.useState)(null);
+  const [isStreaming, setIsStreaming] = (0, import_react3.useState)(false);
+  const [finishReason, setFinishReason] = (0, import_react3.useState)(null);
+  const abortRef = (0, import_react3.useRef)(null);
+  const optionsRef = (0, import_react3.useRef)(options);
+  (0, import_react3.useEffect)(() => {
+    optionsRef.current = options;
+  });
+  const cancel = (0, import_react3.useCallback)(() => {
+    abortRef.current?.abort();
+  }, []);
+  const start = (0, import_react3.useCallback)(async (url, init) => {
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    const { fetchImpl, reconnect, credentials, csrf } = optionsRef.current;
+    const fetchFn = fetchImpl ?? globalThis.fetch;
+    setLastEvent(null);
+    setLastEventId("");
+    setError(null);
+    setFinishReason(null);
+    setIsStreaming(true);
+    let currentLastEventId = "";
+    let serverRetryMs = null;
+    let reason = "interrupted";
+    const requestInit = () => {
+      const merged = { ...init, signal: controller.signal };
+      const effectiveCredentials = init?.credentials ?? credentials;
+      if (effectiveCredentials !== void 0) merged.credentials = effectiveCredentials;
+      let headers = null;
+      const ensureHeaders = () => {
+        if (headers === null) headers = new Headers(init?.headers);
+        return headers;
+      };
+      if (csrf) {
+        const csrfHeader = (0, import_common_core2.csrfHeaderFor)(url, init?.method, csrf);
+        if (csrfHeader && !ensureHeaders().has(csrfHeader[0])) {
+          ensureHeaders().set(csrfHeader[0], csrfHeader[1]);
+        }
+      }
+      if (currentLastEventId !== "") ensureHeaders().set(LAST_EVENT_ID_HEADER, currentLastEventId);
+      if (headers !== null) merged.headers = headers;
+      return merged;
+    };
+    const attemptStream = async (attempt) => {
+      if (attempt > 0) setError(null);
+      let terminal = false;
+      let streamStarted = false;
+      let callbackFailed = false;
+      let callbackError;
+      try {
+        const res = await fetchFn(url, requestInit());
+        if (!res.ok) {
+          const json = await res.json().catch(() => null);
+          setError(typeof json?.message === "string" ? json.message : `HTTP ${res.status}`);
+          return;
+        }
+        if (res.status === 204) {
+          reason = "done";
+          return;
+        }
+        streamStarted = true;
+        const result = await (0, import_common_core2.readSseEvents)(res, {
+          // 연결을 넘어 마지막 이벤트 ID 유지 (EventSource 동일) — id 없는 이벤트도 이어받는다.
+          lastEventId: currentLastEventId,
+          onEvent: (event) => {
+            currentLastEventId = event.id;
+            setLastEvent(event);
+            setLastEventId(event.id);
+            try {
+              optionsRef.current.onEvent?.(event);
+              if (optionsRef.current.isTerminal?.(event) === true) {
+                terminal = true;
+                return true;
+              }
+            } catch (err) {
+              callbackFailed = true;
+              callbackError = err;
+              return true;
+            }
+            return void 0;
+          },
+          onRetry: (ms) => {
+            serverRetryMs = ms;
+          }
+        });
+        currentLastEventId = result.lastEventId;
+        setLastEventId(result.lastEventId);
+      } catch (err) {
+        if (controller.signal.aborted) {
+          reason = "aborted";
+          return;
+        }
+        setError(messageOf(err));
+        if (streamStarted && reconnect) throw RECONNECT_MARKER2;
+        return;
+      }
+      if (controller.signal.aborted) {
+        reason = "aborted";
+        return;
+      }
+      if (callbackFailed) {
+        setError(messageOf(callbackError));
+        return;
+      }
+      if (terminal) {
+        reason = "done";
+        return;
+      }
+      if (reconnect) throw RECONNECT_MARKER2;
+    };
+    try {
+      if (reconnect) {
+        await (0, import_common_core2.retry)(attemptStream, {
+          retries: reconnect.retries ?? 3,
+          minDelayMs: reconnect.minDelayMs ?? 1e3,
+          maxDelayMs: reconnect.maxDelayMs ?? 15e3,
+          factor: reconnect.factor ?? 2,
+          jitter: reconnect.jitter ?? true,
+          shouldRetry: (e) => e === RECONNECT_MARKER2,
+          // 서버 retry: 힌트가 있으면 그 값을 재연결 대기로 (WHATWG reconnection time).
+          overrideDelay: (_e, _attempt, delayMs) => serverRetryMs ?? delayMs,
+          signal: controller.signal
+        });
+      } else {
+        await attemptStream(0);
+      }
+    } catch (err) {
+      if (controller.signal.aborted) {
+        reason = "aborted";
+      } else if (err !== RECONNECT_MARKER2) {
+        setError(messageOf(err));
+      }
+    } finally {
+      if (abortRef.current === controller) {
+        abortRef.current = null;
+        setIsStreaming(false);
+        setFinishReason(reason);
+      }
+    }
+  }, []);
+  (0, import_react3.useEffect)(() => () => abortRef.current?.abort(), []);
+  return { start, cancel, lastEvent, lastEventId, error, isStreaming, finishReason };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   useDebounce,
-  useSse
+  useSse,
+  useSseEvents
 });

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { CsrfOptions, SseSource } from '@rscc/common-core';
+import { CsrfOptions, SseSource, SseEvent } from '@rscc/common-core';
 
 /**
  * value 가 delayMs(ms) 동안 더 이상 바뀌지 않으면 그 값을 반환한다.
@@ -25,6 +25,10 @@ type SseFinishReason = "done" | "aborted" | "interrupted";
  * text/sources/conversationId/error 상태를 초기화한다 (중복 누적 방지).
  * 이어받기(Last-Event-ID)는 비범위 — sse-frames.md 가 `event:`/`id:`/`retry:`
  * 필드를 사용하지 않는다고 명시하므로 재개 지점이 존재하지 않는다.
+ *
+ * 범용 훅 `useSseEvents` 도 같은 옵션을 쓰되 시맨틱이 다르다 — 재연결은 전체 재요청이 아니라
+ * `Last-Event-ID` 이어받기이고, 서버 `retry:` 값이 있으면 계산된 백오프 대신 그 값을 대기로 쓴다
+ * (contracts/sse-events.md §3).
  */
 interface SseReconnectOptions {
     /** 최대 재연결 시도 횟수 (총 연결 = retries + 1). 기본 3. */
@@ -61,6 +65,13 @@ interface UseSseOptions {
      * `init.headers` 에 같은 헤더가 이미 있으면 덮어쓰지 않는다. 재연결 시도마다 쿠키를 다시 읽는다.
      */
     csrf?: boolean | CsrfOptions;
+    /**
+     * 채팅 프레임 리더 선택 (contracts/sse-events.md §4). 기본 `"legacy"` = core `readSseStream`(현행 동작 —
+     * LF `\n\n` 프레임 구분, 첫 `data:` 라인만). `"standard"` = core `readSseChatEvents` — WHATWG 표준 파서 위의
+     * 채팅 어댑터로 CRLF·CR 줄 끝과 멀티라인 `data` 를 받아들이고 `[DONE]` 비교 전 앞뒤 공백을 제거한다
+     * (콜백·종료 사유·재연결 시맨틱은 동일, EOF 잔여 프레임도 레거시처럼 처리).
+     */
+    parser?: "legacy" | "standard";
 }
 interface UseSseReturn {
     /**
@@ -84,6 +95,8 @@ interface UseSseReturn {
 }
 /**
  * @rscc/common-core 의 readSseStream 을 감싼 상태 훅 (contracts/sse-frames.md).
+ * `parser: "standard"` 면 표준 파서 위의 readSseChatEvents 를 쓴다 (contracts/sse-events.md §4).
+ * 채팅 외의 범용 SSE(event/id/retry 필드)는 {@link import("./useSseEvents").useSseEvents} 를 쓴다.
  *
  * - 구독 전 검증 실패(!res.ok — CommonResponse JSON 에러 경로)는 봉투의 message 를 error 로 노출.
  * - 스트림 시작 후 오류는 in-band error 프레임으로 수신되어 동일하게 error 로 노출.
@@ -95,4 +108,73 @@ interface UseSseReturn {
  */
 declare function useSse(options?: UseSseOptions): UseSseReturn;
 
-export { type SseFinishReason, type SseReconnectOptions, type UseSseOptions, type UseSseReturn, useDebounce, useSse };
+interface UseSseEventsOptions {
+    /** fetch 구현체 주입 (테스트용). 기본 globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * 이벤트마다 호출 — 누적이 필요하면 여기서 소비 측 상태에 쌓는다 (훅은 `lastEvent` 1개만 보관).
+     * 호출 시점의 최신 콜백을 쓴다(인라인 함수여도 start 재생성 없음). throw 하면 스트림을 멈추고
+     * error 로 노출하며 재연결하지 않는다.
+     */
+    onEvent?: (event: SseEvent) => void;
+    /**
+     * 종료 이벤트 판정 — true 를 반환한 이벤트(onEvent 전달 후)에서 읽기를 멈추고 연결을 닫으며
+     * finishReason 'done' 으로 끝난다. 미지정이면 모든 종료가 EOF → 'interrupted' 다.
+     */
+    isTerminal?: (event: SseEvent) => boolean;
+    /**
+     * 자동 재연결 — 기본 undefined = off (옵트인). 켜면 "스트림 시작(res.ok) 후 종료 이벤트 없이
+     * 끊김"(EOF·전송 오류)에서 재연결하며 (contracts/sse-events.md §3):
+     * - 마지막 이벤트 ID 가 있으면 `Last-Event-ID` 헤더를 싣는다 (`init.headers` 와 병합 — 같은 이름은 덮어씀).
+     * - 서버가 `retry:` 를 보냈으면 계산된 백오프 대신 그 값(ms)을 재연결 대기로 쓴다.
+     * - 구독 전 실패(!res.ok)·HTTP 204·종료 이벤트·abort·onEvent 예외는 재연결하지 않는다.
+     * 각 재연결은 이어받기이므로 `lastEvent`/`lastEventId` 는 유지하고 `error` 만 초기화한다.
+     */
+    reconnect?: SseReconnectOptions;
+    /**
+     * fetch `credentials` 기본값 — 쿠키 운반 인증 모드(`jwt-cookie`/`session`, contracts/session-auth.md §5)용.
+     * 미지정 = 속성 자체를 넘기지 않음. `start(url, init)` 의 `init.credentials` 가 우선한다.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * CSRF double-submit 헤더 자동 부착 (core `csrfHeaderFor` — 골든 벡터 XC-01~08). 비안전 메서드 +
+     * CSRF 쿠키 + 같은 출처(또는 `allowedOrigins`)일 때만, `init.headers` 의 같은 헤더는 덮어쓰지 않는다.
+     * 재연결 시도마다 쿠키를 다시 읽는다.
+     */
+    csrf?: boolean | CsrfOptions;
+}
+interface UseSseEventsReturn {
+    /**
+     * 구독 시작. 이전 스트림이 진행 중이면 중단 후 상태를 초기화한다. 반환 Promise 는 스트림 종료
+     * (종료 이벤트/중단/오류/재연결 소진) 시 resolve — 오류는 error 상태로 노출되며 reject 하지 않는다.
+     */
+    start: (url: string, init?: RequestInit) => Promise<void>;
+    /** 진행 중인 스트림(또는 재연결 대기) 중단. */
+    cancel: () => void;
+    /** 마지막으로 받은 이벤트 (배열 누적 없음 — 누적은 onEvent 에서). 미수신 시 null. */
+    lastEvent: SseEvent | null;
+    /** 마지막 이벤트 ID (재연결 `Last-Event-ID` 값). 초기값 `""`. */
+    lastEventId: string;
+    /** 구독 전 실패 메시지(CommonResponse message 또는 `HTTP <status>`)·전송 오류·onEvent 예외 메시지. */
+    error: string | null;
+    isStreaming: boolean;
+    /**
+     * 직전 스트림의 종료 사유 — 'done'(isTerminal 이벤트 또는 HTTP 204) / 'aborted'(cancel·재시작·언마운트) /
+     * 'interrupted'(종료 이벤트 없이 끝남 — EOF·전송 오류·구독 전 실패·재연결 소진). 스트리밍 중/시작 전엔 null.
+     */
+    finishReason: SseFinishReason | null;
+}
+/**
+ * 범용 SSE 구독 훅 — @rscc/common-core 의 표준 파서 리더 `readSseEvents` 를 감싼다
+ * (contracts/sse-events.md — WHATWG 이벤트 스트림, `event`/`id`/`retry` 필드).
+ *
+ * - 이벤트마다 `onEvent` 를 부르고 `lastEvent`·`lastEventId` 상태만 갱신한다 (무한 누적 배열 없음).
+ * - `isTerminal` 이벤트에서 연결을 닫고 'done', 그 없이 EOF 면 'interrupted'.
+ * - reconnect 옵트인 시 `Last-Event-ID` 이어받기 + 서버 `retry:` 존중 (core `retry()` 의 overrideDelay 훅).
+ * - 쿠키 인증 모드는 `credentials` + `csrf` (useSse 와 동일 규칙, 호출자 `init` 우선).
+ * - 언마운트·재시작 시 진행 중 스트림을 중단한다 (StrictMode 이중 마운트 안전 — useSse 와 같은 구조).
+ * - 채팅 프레임(sse-frames.md)은 {@link import("./useSse").useSse} 를 쓴다.
+ */
+declare function useSseEvents(options?: UseSseEventsOptions): UseSseEventsReturn;
+
+export { type SseFinishReason, type SseReconnectOptions, type UseSseEventsOptions, type UseSseEventsReturn, type UseSseOptions, type UseSseReturn, useDebounce, useSse, useSseEvents };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CsrfOptions, SseSource } from '@rscc/common-core';
+import { CsrfOptions, SseSource, SseEvent } from '@rscc/common-core';
 
 /**
  * value 가 delayMs(ms) 동안 더 이상 바뀌지 않으면 그 값을 반환한다.
@@ -25,6 +25,10 @@ type SseFinishReason = "done" | "aborted" | "interrupted";
  * text/sources/conversationId/error 상태를 초기화한다 (중복 누적 방지).
  * 이어받기(Last-Event-ID)는 비범위 — sse-frames.md 가 `event:`/`id:`/`retry:`
  * 필드를 사용하지 않는다고 명시하므로 재개 지점이 존재하지 않는다.
+ *
+ * 범용 훅 `useSseEvents` 도 같은 옵션을 쓰되 시맨틱이 다르다 — 재연결은 전체 재요청이 아니라
+ * `Last-Event-ID` 이어받기이고, 서버 `retry:` 값이 있으면 계산된 백오프 대신 그 값을 대기로 쓴다
+ * (contracts/sse-events.md §3).
  */
 interface SseReconnectOptions {
     /** 최대 재연결 시도 횟수 (총 연결 = retries + 1). 기본 3. */
@@ -61,6 +65,13 @@ interface UseSseOptions {
      * `init.headers` 에 같은 헤더가 이미 있으면 덮어쓰지 않는다. 재연결 시도마다 쿠키를 다시 읽는다.
      */
     csrf?: boolean | CsrfOptions;
+    /**
+     * 채팅 프레임 리더 선택 (contracts/sse-events.md §4). 기본 `"legacy"` = core `readSseStream`(현행 동작 —
+     * LF `\n\n` 프레임 구분, 첫 `data:` 라인만). `"standard"` = core `readSseChatEvents` — WHATWG 표준 파서 위의
+     * 채팅 어댑터로 CRLF·CR 줄 끝과 멀티라인 `data` 를 받아들이고 `[DONE]` 비교 전 앞뒤 공백을 제거한다
+     * (콜백·종료 사유·재연결 시맨틱은 동일, EOF 잔여 프레임도 레거시처럼 처리).
+     */
+    parser?: "legacy" | "standard";
 }
 interface UseSseReturn {
     /**
@@ -84,6 +95,8 @@ interface UseSseReturn {
 }
 /**
  * @rscc/common-core 의 readSseStream 을 감싼 상태 훅 (contracts/sse-frames.md).
+ * `parser: "standard"` 면 표준 파서 위의 readSseChatEvents 를 쓴다 (contracts/sse-events.md §4).
+ * 채팅 외의 범용 SSE(event/id/retry 필드)는 {@link import("./useSseEvents").useSseEvents} 를 쓴다.
  *
  * - 구독 전 검증 실패(!res.ok — CommonResponse JSON 에러 경로)는 봉투의 message 를 error 로 노출.
  * - 스트림 시작 후 오류는 in-band error 프레임으로 수신되어 동일하게 error 로 노출.
@@ -95,4 +108,73 @@ interface UseSseReturn {
  */
 declare function useSse(options?: UseSseOptions): UseSseReturn;
 
-export { type SseFinishReason, type SseReconnectOptions, type UseSseOptions, type UseSseReturn, useDebounce, useSse };
+interface UseSseEventsOptions {
+    /** fetch 구현체 주입 (테스트용). 기본 globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * 이벤트마다 호출 — 누적이 필요하면 여기서 소비 측 상태에 쌓는다 (훅은 `lastEvent` 1개만 보관).
+     * 호출 시점의 최신 콜백을 쓴다(인라인 함수여도 start 재생성 없음). throw 하면 스트림을 멈추고
+     * error 로 노출하며 재연결하지 않는다.
+     */
+    onEvent?: (event: SseEvent) => void;
+    /**
+     * 종료 이벤트 판정 — true 를 반환한 이벤트(onEvent 전달 후)에서 읽기를 멈추고 연결을 닫으며
+     * finishReason 'done' 으로 끝난다. 미지정이면 모든 종료가 EOF → 'interrupted' 다.
+     */
+    isTerminal?: (event: SseEvent) => boolean;
+    /**
+     * 자동 재연결 — 기본 undefined = off (옵트인). 켜면 "스트림 시작(res.ok) 후 종료 이벤트 없이
+     * 끊김"(EOF·전송 오류)에서 재연결하며 (contracts/sse-events.md §3):
+     * - 마지막 이벤트 ID 가 있으면 `Last-Event-ID` 헤더를 싣는다 (`init.headers` 와 병합 — 같은 이름은 덮어씀).
+     * - 서버가 `retry:` 를 보냈으면 계산된 백오프 대신 그 값(ms)을 재연결 대기로 쓴다.
+     * - 구독 전 실패(!res.ok)·HTTP 204·종료 이벤트·abort·onEvent 예외는 재연결하지 않는다.
+     * 각 재연결은 이어받기이므로 `lastEvent`/`lastEventId` 는 유지하고 `error` 만 초기화한다.
+     */
+    reconnect?: SseReconnectOptions;
+    /**
+     * fetch `credentials` 기본값 — 쿠키 운반 인증 모드(`jwt-cookie`/`session`, contracts/session-auth.md §5)용.
+     * 미지정 = 속성 자체를 넘기지 않음. `start(url, init)` 의 `init.credentials` 가 우선한다.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * CSRF double-submit 헤더 자동 부착 (core `csrfHeaderFor` — 골든 벡터 XC-01~08). 비안전 메서드 +
+     * CSRF 쿠키 + 같은 출처(또는 `allowedOrigins`)일 때만, `init.headers` 의 같은 헤더는 덮어쓰지 않는다.
+     * 재연결 시도마다 쿠키를 다시 읽는다.
+     */
+    csrf?: boolean | CsrfOptions;
+}
+interface UseSseEventsReturn {
+    /**
+     * 구독 시작. 이전 스트림이 진행 중이면 중단 후 상태를 초기화한다. 반환 Promise 는 스트림 종료
+     * (종료 이벤트/중단/오류/재연결 소진) 시 resolve — 오류는 error 상태로 노출되며 reject 하지 않는다.
+     */
+    start: (url: string, init?: RequestInit) => Promise<void>;
+    /** 진행 중인 스트림(또는 재연결 대기) 중단. */
+    cancel: () => void;
+    /** 마지막으로 받은 이벤트 (배열 누적 없음 — 누적은 onEvent 에서). 미수신 시 null. */
+    lastEvent: SseEvent | null;
+    /** 마지막 이벤트 ID (재연결 `Last-Event-ID` 값). 초기값 `""`. */
+    lastEventId: string;
+    /** 구독 전 실패 메시지(CommonResponse message 또는 `HTTP <status>`)·전송 오류·onEvent 예외 메시지. */
+    error: string | null;
+    isStreaming: boolean;
+    /**
+     * 직전 스트림의 종료 사유 — 'done'(isTerminal 이벤트 또는 HTTP 204) / 'aborted'(cancel·재시작·언마운트) /
+     * 'interrupted'(종료 이벤트 없이 끝남 — EOF·전송 오류·구독 전 실패·재연결 소진). 스트리밍 중/시작 전엔 null.
+     */
+    finishReason: SseFinishReason | null;
+}
+/**
+ * 범용 SSE 구독 훅 — @rscc/common-core 의 표준 파서 리더 `readSseEvents` 를 감싼다
+ * (contracts/sse-events.md — WHATWG 이벤트 스트림, `event`/`id`/`retry` 필드).
+ *
+ * - 이벤트마다 `onEvent` 를 부르고 `lastEvent`·`lastEventId` 상태만 갱신한다 (무한 누적 배열 없음).
+ * - `isTerminal` 이벤트에서 연결을 닫고 'done', 그 없이 EOF 면 'interrupted'.
+ * - reconnect 옵트인 시 `Last-Event-ID` 이어받기 + 서버 `retry:` 존중 (core `retry()` 의 overrideDelay 훅).
+ * - 쿠키 인증 모드는 `credentials` + `csrf` (useSse 와 동일 규칙, 호출자 `init` 우선).
+ * - 언마운트·재시작 시 진행 중 스트림을 중단한다 (StrictMode 이중 마운트 안전 — useSse 와 같은 구조).
+ * - 채팅 프레임(sse-frames.md)은 {@link import("./useSse").useSse} 를 쓴다.
+ */
+declare function useSseEvents(options?: UseSseEventsOptions): UseSseEventsReturn;
+
+export { type SseFinishReason, type SseReconnectOptions, type UseSseEventsOptions, type UseSseEventsReturn, type UseSseOptions, type UseSseReturn, useDebounce, useSse, useSseEvents };

package/dist/index.js

@@ -13,12 +13,13 @@ function useDebounce(value, delayMs = 200) {
 import { useCallback, useEffect as useEffect2, useRef, useState as useState2 } from "react";
 import {
   csrfHeaderFor,
+  readSseChatEvents,
   readSseStream,
   retry
 } from "@rscc/common-core";
 var RECONNECT_MARKER = new Error("rscc-sse-reconnect");
 function useSse(options = {}) {
-  const { fetchImpl, reconnect, credentials, csrf } = options;
+  const { fetchImpl, reconnect, credentials, csrf, parser = "legacy" } = options;
   const [text, setText] = useState2("");
   const [sources, setSources] = useState2(null);
   const [conversationId, setConversationId] = useState2(null);
@@ -74,7 +75,8 @@ function useSse(options = {}) {
             return;
           }
           streamStarted = true;
-          await readSseStream(res, {
+          const readChat = parser === "standard" ? readSseChatEvents : readSseStream;
+          await readChat(res, {
             onConversationId: setConversationId,
             onSources: setSources,
             onDelta: (d) => setText((prev) => prev + d),
@@ -133,12 +135,171 @@ function useSse(options = {}) {
         }
       }
     },
-    [fetchImpl, reconnect, credentials, csrf]
+    [fetchImpl, reconnect, credentials, csrf, parser]
   );
   useEffect2(() => () => abortRef.current?.abort(), []);
   return { start, cancel, text, sources, conversationId, error, isStreaming, finishReason };
 }
+
+// src/useSseEvents.ts
+import { useCallback as useCallback2, useEffect as useEffect3, useRef as useRef2, useState as useState3 } from "react";
+import {
+  csrfHeaderFor as csrfHeaderFor2,
+  readSseEvents,
+  retry as retry2
+} from "@rscc/common-core";
+var RECONNECT_MARKER2 = new Error("rscc-sse-events-reconnect");
+var LAST_EVENT_ID_HEADER = "Last-Event-ID";
+var messageOf = (err) => err instanceof Error ? err.message : String(err);
+function useSseEvents(options = {}) {
+  const [lastEvent, setLastEvent] = useState3(null);
+  const [lastEventId, setLastEventId] = useState3("");
+  const [error, setError] = useState3(null);
+  const [isStreaming, setIsStreaming] = useState3(false);
+  const [finishReason, setFinishReason] = useState3(null);
+  const abortRef = useRef2(null);
+  const optionsRef = useRef2(options);
+  useEffect3(() => {
+    optionsRef.current = options;
+  });
+  const cancel = useCallback2(() => {
+    abortRef.current?.abort();
+  }, []);
+  const start = useCallback2(async (url, init) => {
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    const { fetchImpl, reconnect, credentials, csrf } = optionsRef.current;
+    const fetchFn = fetchImpl ?? globalThis.fetch;
+    setLastEvent(null);
+    setLastEventId("");
+    setError(null);
+    setFinishReason(null);
+    setIsStreaming(true);
+    let currentLastEventId = "";
+    let serverRetryMs = null;
+    let reason = "interrupted";
+    const requestInit = () => {
+      const merged = { ...init, signal: controller.signal };
+      const effectiveCredentials = init?.credentials ?? credentials;
+      if (effectiveCredentials !== void 0) merged.credentials = effectiveCredentials;
+      let headers = null;
+      const ensureHeaders = () => {
+        if (headers === null) headers = new Headers(init?.headers);
+        return headers;
+      };
+      if (csrf) {
+        const csrfHeader = csrfHeaderFor2(url, init?.method, csrf);
+        if (csrfHeader && !ensureHeaders().has(csrfHeader[0])) {
+          ensureHeaders().set(csrfHeader[0], csrfHeader[1]);
+        }
+      }
+      if (currentLastEventId !== "") ensureHeaders().set(LAST_EVENT_ID_HEADER, currentLastEventId);
+      if (headers !== null) merged.headers = headers;
+      return merged;
+    };
+    const attemptStream = async (attempt) => {
+      if (attempt > 0) setError(null);
+      let terminal = false;
+      let streamStarted = false;
+      let callbackFailed = false;
+      let callbackError;
+      try {
+        const res = await fetchFn(url, requestInit());
+        if (!res.ok) {
+          const json = await res.json().catch(() => null);
+          setError(typeof json?.message === "string" ? json.message : `HTTP ${res.status}`);
+          return;
+        }
+        if (res.status === 204) {
+          reason = "done";
+          return;
+        }
+        streamStarted = true;
+        const result = await readSseEvents(res, {
+          // 연결을 넘어 마지막 이벤트 ID 유지 (EventSource 동일) — id 없는 이벤트도 이어받는다.
+          lastEventId: currentLastEventId,
+          onEvent: (event) => {
+            currentLastEventId = event.id;
+            setLastEvent(event);
+            setLastEventId(event.id);
+            try {
+              optionsRef.current.onEvent?.(event);
+              if (optionsRef.current.isTerminal?.(event) === true) {
+                terminal = true;
+                return true;
+              }
+            } catch (err) {
+              callbackFailed = true;
+              callbackError = err;
+              return true;
+            }
+            return void 0;
+          },
+          onRetry: (ms) => {
+            serverRetryMs = ms;
+          }
+        });
+        currentLastEventId = result.lastEventId;
+        setLastEventId(result.lastEventId);
+      } catch (err) {
+        if (controller.signal.aborted) {
+          reason = "aborted";
+          return;
+        }
+        setError(messageOf(err));
+        if (streamStarted && reconnect) throw RECONNECT_MARKER2;
+        return;
+      }
+      if (controller.signal.aborted) {
+        reason = "aborted";
+        return;
+      }
+      if (callbackFailed) {
+        setError(messageOf(callbackError));
+        return;
+      }
+      if (terminal) {
+        reason = "done";
+        return;
+      }
+      if (reconnect) throw RECONNECT_MARKER2;
+    };
+    try {
+      if (reconnect) {
+        await retry2(attemptStream, {
+          retries: reconnect.retries ?? 3,
+          minDelayMs: reconnect.minDelayMs ?? 1e3,
+          maxDelayMs: reconnect.maxDelayMs ?? 15e3,
+          factor: reconnect.factor ?? 2,
+          jitter: reconnect.jitter ?? true,
+          shouldRetry: (e) => e === RECONNECT_MARKER2,
+          // 서버 retry: 힌트가 있으면 그 값을 재연결 대기로 (WHATWG reconnection time).
+          overrideDelay: (_e, _attempt, delayMs) => serverRetryMs ?? delayMs,
+          signal: controller.signal
+        });
+      } else {
+        await attemptStream(0);
+      }
+    } catch (err) {
+      if (controller.signal.aborted) {
+        reason = "aborted";
+      } else if (err !== RECONNECT_MARKER2) {
+        setError(messageOf(err));
+      }
+    } finally {
+      if (abortRef.current === controller) {
+        abortRef.current = null;
+        setIsStreaming(false);
+        setFinishReason(reason);
+      }
+    }
+  }, []);
+  useEffect3(() => () => abortRef.current?.abort(), []);
+  return { start, cancel, lastEvent, lastEventId, error, isStreaming, finishReason };
+}
 export {
   useDebounce,
-  useSse
+  useSse,
+  useSseEvents
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rscc/common-react",
-  "version": "0.4.0",
-  "description": "RSCC 공통 React 훅 — useDebounce, useSse (@rscc/common-core 의 SSE 파서 래핑).",
+  "version": "0.5.0",
+  "description": "RSCC 공통 React 훅 — useDebounce, useSse(채팅 SSE), useSseEvents(범용 SSE — Last-Event-ID 재연결) (@rscc/common-core 래핑).",
   "keywords": [
     "rscc",
     "react",
@@ -54,7 +54,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@rscc/common-core": "^0.4.0"
+    "@rscc/common-core": "^0.5.0"
   },
   "peerDependencies": {
     "react": ">=18"