@rscc/common-react 0.2.0 → 0.4.0

package/README.md

@@ -10,14 +10,17 @@ npm i @rscc/common-react
 
 - **peerDependencies: `react >= 18`** — 소비 앱이 직접 설치
 - `@rscc/common-core` 는 `^` 범위 의존으로 함께 설치된다 (두 패키지는 락스텝 버전)
-- **Node >= 18**, ESM + CJS 듀얼 빌드, 타입 선언 동봉
+- **Node >= 20**, ESM + CJS 듀얼 빌드, 타입 선언 동봉
 
 ## 훅
 
 | 훅 | 시그니처 | 설명 |
 |---|---|---|
 | `useDebounce` | `useDebounce<T>(value, delayMs = 200): T` | 마지막 안정 값만 통과 — 자동완성 API 호출 절감 |
-| `useSse` | `useSse(options?)` → `{ start, cancel, text, sources, conversationId, error, isStreaming }` | SSE 구독 상태 훅 — 언마운트 시 자동 중단 |
+| `useSse` | `useSse(options?)` → `{ start, cancel, text, sources, conversationId, error, isStreaming, finishReason }` | SSE 구독 상태 훅 — 언마운트 시 자동 중단, `finishReason` 으로 종료 사유 구분, opt-in `reconnect`, 쿠키 인증 모드용 `credentials`·`csrf` |
+
+`UseSseOptions`: `fetchImpl?` · `reconnect?: SseReconnectOptions` · `credentials?: RequestCredentials` · `csrf?: boolean | CsrfOptions`
+(`CsrfOptions` 는 `@rscc/common-core` 에서 export).
 
 ## 사용 예시
 
@@ -35,19 +38,68 @@ const debounced = useDebounce(keyword, 200);
 ```ts
 import { useSse } from "@rscc/common-react";
 
-const { start, cancel, text, sources, conversationId, error, isStreaming } = useSse();
+const { start, cancel, text, sources, conversationId, error, isStreaming, finishReason } = useSse();
 
 await start("/api/v1/chat/stream", { method: "POST", headers, body });
 // text: delta 누적 텍스트, sources: RAG 근거, error: in-band 오류 메시지
 // cancel(): 중단 — 그때까지의 text 는 보존되고 error 는 남지 않는다
+// finishReason: 직전 스트림의 종료 사유 — 스트리밍 중/시작 전엔 null
 ```
 
 - 구독 전 검증 실패(`!res.ok`)는 응답 봉투의 `message` 를 `error` 로 노출한다.
 - `start` 재호출 시 이전 스트림을 중단하고 상태를 초기화한다.
-- 한계: `[DONE]` 정상 종료와 끊긴 스트림을 구분하는 신호가 없다 — 둘 다 `isStreaming=false`, `error=null` 로 끝난다.
+- 반환 Promise 는 스트림 종료 시 resolve 한다 — 오류는 `error` 상태로 노출되며 reject 하지 않는다.
+
+`finishReason` (`SseFinishReason`) 으로 정상 종료와 끊김을 구분한다:
+
+| 값 | 의미 |
+|---|---|
+| `'done'` | `[DONE]` 종료 마커 수신 (in-band error 프레임 뒤의 `[DONE]` 포함 — `error` 와 공존) |
+| `'aborted'` | `cancel()` / 새 `start()` 로 대체 / 언마운트로 인한 중단 |
+| `'interrupted'` | `[DONE]` 없이 끝난 비정상 종료 — 무언 EOF, 전송 오류, 구독 전 검증 실패(`!res.ok`) 포함 |
+
+### useSse — 자동 재연결 (opt-in, 기본 off)
+
+```ts
+const sse = useSse({ reconnect: { retries: 3, minDelayMs: 1000, maxDelayMs: 15000 } });
+// 기본값: retries 3 · minDelayMs 1000 · maxDelayMs 15000 · factor 2 · jitter true (SseReconnectOptions)
+```
+
+- 재연결 트리거는 **"스트림 시작(`res.ok`) 후 `[DONE]` 없이 끊긴 경우"뿐** — `'done'`/`'aborted'`/
+  구독 전 실패(`!res.ok`)/in-band error 프레임 종료는 서버 의도로 보고 재연결하지 않는다.
+- 각 시도는 **전체 재요청**이며 직전 시도의 `text`/`sources`/`conversationId`/`error` 를 초기화한다
+  (중복 누적 방지). 이어받기(Last-Event-ID)는 지원하지 않는다.
+- [주의] 비멱등 POST 스트림은 전체 재요청이 서버 측 중복 생성으로 이어질 수 있으므로 멱등성이 보장될 때만 켤 것.
+
+### useSse — 쿠키 인증 모드 (credentials / CSRF)
+
+서버가 인증 자격을 HttpOnly 쿠키(`jwt-cookie`) 또는 서버 세션(`session`)으로 받는다면 `credentials` 와 `csrf` 를 켠다.
+채팅 스트림은 보통 POST 라 CSRF 헤더가 필요하다. 서버가 `bearer`(기본)면 지금처럼 `init.headers` 에
+`Authorization: Bearer …` 를 직접 싣는다.
+
+```ts
+// 같은 출처 (리버스 프록시로 프론트와 API 를 한 오리진에 — 권장)
+const sse = useSse({ credentials: "same-origin", csrf: true });
+await sse.start("/api/v1/chat/stream", { method: "POST", headers, body }); // X-XSRF-TOKEN 자동 부착
+
+// 같은 사이트 서브도메인 (app.example.com → api.example.com)
+const sse2 = useSse({
+  credentials: "include",
+  csrf: { allowedOrigins: ["https://api.example.com"] },
+});
+```
+
+- **`credentials`**: 미지정이면 fetch 에 속성 자체를 넘기지 않는다(현행 동작). `start(url, init)` 의 `init.credentials` 가 우선한다.
+- **`csrf`** (`true` | `CsrfOptions`): 쿠키 `XSRF-TOKEN` 의 값을 `X-XSRF-TOKEN` 헤더로 싣는다 — **비안전 메서드**
+  (GET·HEAD·OPTIONS·TRACE 외)이고 쿠키가 있으며 URL 이 **같은 출처**(상대 URL 포함)이거나 `allowedOrigins` 에 속할 때만.
+  교차 출처로는 보내지 않는다. `init.headers` 에 같은 헤더가 이미 있으면 덮어쓰지 않고, 재연결 시도마다 쿠키를 다시 읽는다.
+  `CsrfOptions` 의 `cookieName`·`headerName`·`readCookie`(React Native·테스트용 원시 쿠키 문자열 공급자)로 바꿀 수 있다.
+- SSR(`document` 없음)에서는 아무것도 붙이지 않고 오류도 내지 않는다.
+- 쿠키 모드에서는 **토큰을 localStorage 등에 저장하지 않는다** — 로그인 상태는 토큰 만료 계산(`isTokenExpired`) 대신
+  `/me` 같은 서버 엔드포인트로 확인한다.
+- 일반 API 호출은 `@rscc/common-core` 의 `createApiClient({ credentials, csrf })` 로 같은 규칙을 쓴다.
 
-## 문서 / 저장소
+## 관련 패키지
 
-- 상세 문서: [js/README.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/js/README.md)
-- SSE 프레임 계약: [contracts/sse-frames.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/contracts/sse-frames.md)
-- 저장소: [Jeonghyeon-Ryu/r-common](https://github.com/Jeonghyeon-Ryu/r-common) · MIT
+- 코어(SSE 파서 `readSseStream`·apiClient 등): [@rscc/common-core](https://www.npmjs.com/package/@rscc/common-core)
+- 라이선스: MIT

package/dist/index.cjs

@@ -41,7 +41,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 } = options;
+  const { fetchImpl, reconnect, credentials, csrf } = options;
   const [text, setText] = (0, import_react2.useState)("");
   const [sources, setSources] = (0, import_react2.useState)(null);
   const [conversationId, setConversationId] = (0, import_react2.useState)(null);
@@ -67,6 +67,22 @@ function useSse(options = {}) {
       setFinishReason(null);
       setIsStreaming(true);
       const fetchFn = fetchImpl ?? globalThis.fetch;
+      const requestInit = () => {
+        const merged = { ...init, signal: controller.signal };
+        const effectiveCredentials = init?.credentials ?? credentials;
+        if (effectiveCredentials !== void 0) merged.credentials = effectiveCredentials;
+        if (csrf) {
+          const csrfHeader = (0, import_common_core.csrfHeaderFor)(url, init?.method, csrf);
+          if (csrfHeader) {
+            const headers = new Headers(init?.headers);
+            if (!headers.has(csrfHeader[0])) {
+              headers.set(csrfHeader[0], csrfHeader[1]);
+              merged.headers = headers;
+            }
+          }
+        }
+        return merged;
+      };
       let reason = "interrupted";
       const attemptStream = async (attempt) => {
         if (attempt > 0) resetStreamState();
@@ -74,7 +90,7 @@ function useSse(options = {}) {
         let sawErrorFrame = false;
         let streamStarted = false;
         try {
-          const res = await fetchFn(url, { ...init, signal: controller.signal });
+          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}`);
@@ -140,7 +156,7 @@ function useSse(options = {}) {
         }
       }
     },
-    [fetchImpl, reconnect]
+    [fetchImpl, reconnect, credentials, csrf]
   );
   (0, import_react2.useEffect)(() => () => abortRef.current?.abort(), []);
   return { start, cancel, text, sources, conversationId, error, isStreaming, finishReason };

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { SseSource } from '@rscc/common-core';
+import { CsrfOptions, SseSource } from '@rscc/common-core';
 
 /**
  * value 가 delayMs(ms) 동안 더 이상 바뀌지 않으면 그 값을 반환한다.
@@ -46,6 +46,21 @@ interface UseSseOptions {
      * 서버 측 중복 생성으로 이어질 수 있으므로 멱등성이 보장될 때만 켤 것).
      */
     reconnect?: SseReconnectOptions;
+    /**
+     * fetch `credentials` 기본값 — 쿠키 운반 인증 모드(`jwt-cookie`/`session`, contracts/session-auth.md §5)용.
+     * 같은 출처 `"same-origin"`(fetch 기본값), 교차 출처(서브도메인 API) `"include"`.
+     * 미지정 = 속성 자체를 넘기지 않음 (현행 동작). `start(url, init)` 의 `init.credentials` 가 우선한다.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * CSRF double-submit 헤더 자동 부착 (core `csrfHeaderFor` — 골든 벡터 XC-01~08). 채팅 스트림은 보통
+     * POST 라 쿠키 모드에서 필요하다. `true` = 기본값(쿠키 `XSRF-TOKEN` → 헤더 `X-XSRF-TOKEN`, 같은 출처만),
+     * 객체 = `CsrfOptions`(`allowedOrigins`·`readCookie` 등). 미지정/false = 부착 안 함 (현행 동작).
+     *
+     * 비안전 메서드 + CSRF 쿠키 존재 + 같은 출처(상대 URL 포함) 또는 `allowedOrigins` 일 때만 붙이고,
+     * `init.headers` 에 같은 헤더가 이미 있으면 덮어쓰지 않는다. 재연결 시도마다 쿠키를 다시 읽는다.
+     */
+    csrf?: boolean | CsrfOptions;
 }
 interface UseSseReturn {
     /**
@@ -73,6 +88,7 @@ interface UseSseReturn {
  * - 구독 전 검증 실패(!res.ok — CommonResponse JSON 에러 경로)는 봉투의 message 를 error 로 노출.
  * - 스트림 시작 후 오류는 in-band error 프레임으로 수신되어 동일하게 error 로 노출.
  * - 언마운트 시 진행 중 스트림을 자동 중단한다.
+ * - 쿠키 인증 모드(contracts/session-auth.md)는 `credentials` + `csrf` 옵션으로 — 호출자 `init` 이 우선한다.
  * - 종료 사유는 finishReason 으로 구분한다 — 'done'([DONE] 수신) / 'aborted'(중단) /
  *   'interrupted'([DONE] 없이 끊김). reconnect 옵트인 시 'interrupted' 성 종료 중
  *   "스트림 시작 후 끊김"만 지수 백오프로 전체 재요청한다 ({@link SseReconnectOptions}).

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SseSource } from '@rscc/common-core';
+import { CsrfOptions, SseSource } from '@rscc/common-core';
 
 /**
  * value 가 delayMs(ms) 동안 더 이상 바뀌지 않으면 그 값을 반환한다.
@@ -46,6 +46,21 @@ interface UseSseOptions {
      * 서버 측 중복 생성으로 이어질 수 있으므로 멱등성이 보장될 때만 켤 것).
      */
     reconnect?: SseReconnectOptions;
+    /**
+     * fetch `credentials` 기본값 — 쿠키 운반 인증 모드(`jwt-cookie`/`session`, contracts/session-auth.md §5)용.
+     * 같은 출처 `"same-origin"`(fetch 기본값), 교차 출처(서브도메인 API) `"include"`.
+     * 미지정 = 속성 자체를 넘기지 않음 (현행 동작). `start(url, init)` 의 `init.credentials` 가 우선한다.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * CSRF double-submit 헤더 자동 부착 (core `csrfHeaderFor` — 골든 벡터 XC-01~08). 채팅 스트림은 보통
+     * POST 라 쿠키 모드에서 필요하다. `true` = 기본값(쿠키 `XSRF-TOKEN` → 헤더 `X-XSRF-TOKEN`, 같은 출처만),
+     * 객체 = `CsrfOptions`(`allowedOrigins`·`readCookie` 등). 미지정/false = 부착 안 함 (현행 동작).
+     *
+     * 비안전 메서드 + CSRF 쿠키 존재 + 같은 출처(상대 URL 포함) 또는 `allowedOrigins` 일 때만 붙이고,
+     * `init.headers` 에 같은 헤더가 이미 있으면 덮어쓰지 않는다. 재연결 시도마다 쿠키를 다시 읽는다.
+     */
+    csrf?: boolean | CsrfOptions;
 }
 interface UseSseReturn {
     /**
@@ -73,6 +88,7 @@ interface UseSseReturn {
  * - 구독 전 검증 실패(!res.ok — CommonResponse JSON 에러 경로)는 봉투의 message 를 error 로 노출.
  * - 스트림 시작 후 오류는 in-band error 프레임으로 수신되어 동일하게 error 로 노출.
  * - 언마운트 시 진행 중 스트림을 자동 중단한다.
+ * - 쿠키 인증 모드(contracts/session-auth.md)는 `credentials` + `csrf` 옵션으로 — 호출자 `init` 이 우선한다.
  * - 종료 사유는 finishReason 으로 구분한다 — 'done'([DONE] 수신) / 'aborted'(중단) /
  *   'interrupted'([DONE] 없이 끊김). reconnect 옵트인 시 'interrupted' 성 종료 중
  *   "스트림 시작 후 끊김"만 지수 백오프로 전체 재요청한다 ({@link SseReconnectOptions}).

package/dist/index.js

@@ -11,10 +11,14 @@ function useDebounce(value, delayMs = 200) {
 
 // src/useSse.ts
 import { useCallback, useEffect as useEffect2, useRef, useState as useState2 } from "react";
-import { readSseStream, retry } from "@rscc/common-core";
+import {
+  csrfHeaderFor,
+  readSseStream,
+  retry
+} from "@rscc/common-core";
 var RECONNECT_MARKER = new Error("rscc-sse-reconnect");
 function useSse(options = {}) {
-  const { fetchImpl, reconnect } = options;
+  const { fetchImpl, reconnect, credentials, csrf } = options;
   const [text, setText] = useState2("");
   const [sources, setSources] = useState2(null);
   const [conversationId, setConversationId] = useState2(null);
@@ -40,6 +44,22 @@ function useSse(options = {}) {
       setFinishReason(null);
       setIsStreaming(true);
       const fetchFn = fetchImpl ?? globalThis.fetch;
+      const requestInit = () => {
+        const merged = { ...init, signal: controller.signal };
+        const effectiveCredentials = init?.credentials ?? credentials;
+        if (effectiveCredentials !== void 0) merged.credentials = effectiveCredentials;
+        if (csrf) {
+          const csrfHeader = csrfHeaderFor(url, init?.method, csrf);
+          if (csrfHeader) {
+            const headers = new Headers(init?.headers);
+            if (!headers.has(csrfHeader[0])) {
+              headers.set(csrfHeader[0], csrfHeader[1]);
+              merged.headers = headers;
+            }
+          }
+        }
+        return merged;
+      };
       let reason = "interrupted";
       const attemptStream = async (attempt) => {
         if (attempt > 0) resetStreamState();
@@ -47,7 +67,7 @@ function useSse(options = {}) {
         let sawErrorFrame = false;
         let streamStarted = false;
         try {
-          const res = await fetchFn(url, { ...init, signal: controller.signal });
+          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}`);
@@ -113,7 +133,7 @@ function useSse(options = {}) {
         }
       }
     },
-    [fetchImpl, reconnect]
+    [fetchImpl, reconnect, credentials, csrf]
   );
   useEffect2(() => () => abortRef.current?.abort(), []);
   return { start, cancel, text, sources, conversationId, error, isStreaming, finishReason };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rscc/common-react",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "RSCC 공통 React 훅 — useDebounce, useSse (@rscc/common-core 의 SSE 파서 래핑).",
   "keywords": [
     "rscc",
@@ -23,7 +23,7 @@
     "url": "https://github.com/Jeonghyeon-Ryu/r-common/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
@@ -54,7 +54,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@rscc/common-core": "^0.2.0"
+    "@rscc/common-core": "^0.4.0"
   },
   "peerDependencies": {
     "react": ">=18"