@uniai-fe/uds-templates 0.10.0 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -44,7 +44,7 @@
     "@uniai-fe/util-next": "^0.3.0 || ^0.4.0 || ^0.5.0",
     "@uniai-fe/util-rtc": "^0.1.4 || ^0.2.0",
     "jotai": ">=2 <3",
-    "next": ">=16 <17",
+    "next": ">=15.5.20 <17",
     "react": ">=19 <20",
     "react-dom": ">=19 <20",
     "react-hook-form": ">=7 <8",
@@ -67,17 +67,17 @@
     "react-hook-form": "^7.80.0",
     "sass": "^1.101.0",
     "typescript": "6.0.3",
-    "@uniai-fe/eslint-config": "0.4.0",
     "@uniai-fe/next-devkit": "0.4.0",
+    "@uniai-fe/eslint-config": "0.4.1",
+    "@uniai-fe/util-api": "0.2.1",
     "@uniai-fe/tsconfig": "0.2.0",
     "@uniai-fe/react-hooks": "0.3.0",
-    "@uniai-fe/uds-primitives": "0.10.0",
-    "@uniai-fe/util-functions": "0.4.1",
-    "@uniai-fe/uds-foundation": "0.5.0",
+    "@uniai-fe/util-functions": "0.4.3",
     "@uniai-fe/util-jotai": "0.3.0",
-    "@uniai-fe/util-api": "0.2.1",
-    "@uniai-fe/util-next": "0.5.0",
-    "@uniai-fe/util-rtc": "0.2.0"
+    "@uniai-fe/uds-foundation": "0.5.0",
+    "@uniai-fe/uds-primitives": "0.10.0",
+    "@uniai-fe/util-rtc": "0.2.0",
+    "@uniai-fe/util-next": "0.5.0"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

package/src/cctv/apis/client.ts

@@ -41,7 +41,7 @@ class CctvRtcTokenRequestError extends Error {
 /**
  * CCTV; RTC token direct response guard
  * @param {unknown} payload 검사할 token response payload
- * @returns {payload is API_Res_CctvRtcToken} direct `{ token }` 응답 여부
+ * @returns {payload is API_Res_CctvRtcToken} direct `{ token, session_ref }` 응답 여부
  */
 const isCctvRtcTokenResponse = (
   payload: unknown,
@@ -53,7 +53,10 @@ const isCctvRtcTokenResponse = (
   const nextPayload = payload as Partial<API_Res_CctvRtcToken>;
 
   return (
-    typeof nextPayload.token === "string" && nextPayload.token.trim() !== ""
+    typeof nextPayload.token === "string" &&
+    nextPayload.token.trim() !== "" &&
+    typeof nextPayload.session_ref === "string" &&
+    nextPayload.session_ref.trim() !== ""
   );
 };
 
@@ -62,7 +65,8 @@ const isCctvRtcTokenResponse = (
  * @param {unknown} payload service token route 응답 payload
  * @returns {API_Res_CctvRtcToken | null} 사용 가능한 token 응답
  * @desc
- * service route가 direct `{ token }` 또는 API base `{ data: { token } }`를 반환하는 경우를 모두 소비한다.
+ * service route가 direct `{ token, session_ref }` 또는 API base
+ * `{ data: { token, session_ref } }`를 반환하는 경우를 모두 소비한다.
  */
 const getCctvRtcTokenResponse = (
   payload: unknown,
@@ -181,7 +185,7 @@ export const postCctvRtcToken = async ({
 
   if (!tokenResponse) {
     throw new CctvRtcTokenRequestError(
-      "CCTV token response is missing token.",
+      "CCTV token response is missing token or session_ref.",
       response.status,
     );
   }

package/src/cctv/hooks/useContext.ts

@@ -35,7 +35,7 @@ import { cctvRtcLiveRegistryAtom } from "../jotai/rtc";
  *   selectedCompany, // 선택된 회사 데이터
  *   selectedCam, // 선택된 카메라 데이터
  *   groups, // 회사 그룹/회사/카메라 리스트 구조 데이터
- *   companyValidList, // 온라인 카메라가 하나라도 있는 회사 ID 리스트
+ *   companyValidList, // 카메라가 하나라도 있는 회사 ID 리스트
  *   cams, // 선택된 회사의 카메라 리스트
  *   onToggleCamera(cam_id), // 카메라 선택 토글 함수
  *   onOpenCamera(cam_id), // 카메라 선택 함수
@@ -159,14 +159,12 @@ export default function useCctvContext(): UseCctvContextReturn {
     [selectedCamId, selectedCompanyId, groups],
   );
 
-  // 온라인 카메라가 하나라도 있는 company_id만 필터링한다.
+  // cam_online 상태와 무관하게 카메라가 하나라도 있는 company_id를 반환한다.
   const companyValidList = useMemo(
     () =>
       groups
         .flatMap(({ list }) => list)
-        .filter(
-          ({ cam_list }) => !cam_list.every(({ cam_online }) => !cam_online),
-        )
+        .filter(({ cam_list }) => cam_list.length > 0)
         .map(({ company_id }) => company_id),
     [groups],
   );

package/src/cctv/hooks/useRtcStream.ts

@@ -238,27 +238,39 @@ export function useCctvRtcStream({
   const endpointUsername =
     whepUsername === undefined ? tokenUsername : whepUsername;
 
-  // 카메라의 RTC 엔드포인트와 사용자명을 조합해 실제 WHEP endpoint를 계산한다.
-  const endpoint = (() => {
+  // 카메라의 RTC 엔드포인트와 사용자명을 조합해 stable WHEP identity endpoint를 계산한다.
+  const streamIdentityEndpoint = (() => {
     // cam_rtc가 없으면 WHEP endpoint를 만들 수 없어 이후 identity/token gate도 닫힌다.
     if (!cam?.cam_rtc) return undefined;
 
+    // cam_rtc 뒤의 slash 중복을 제거하고 WHEP path를 붙인다.
+    const nextEndpoint = new URL(`${cam.cam_rtc.replace(/\/$/, "")}/whep`);
+
     // WHEP username override가 있으면 token username과 별개로 endpoint query에만 반영한다.
-    const query = endpointUsername
-      ? `?username=${encodeURIComponent(endpointUsername)}`
-      : "";
+    if (endpointUsername) {
+      nextEndpoint.searchParams.set("username", endpointUsername);
+    }
 
-    // cam_rtc 뒤의 slash 중복을 제거하고 WHEP path를 붙인다.
-    return `${cam.cam_rtc.replace(/\/$/, "")}/whep${query}`;
+    return nextEndpoint.toString();
   })();
 
   const streamIdentityKey = (() => {
     // identity 필수값이 모두 있어야 scheduler와 registry identity cleanup이 가능하다.
-    if (!tokenUsername || !cam?.company_id || !cam.cam_id || !endpoint)
+    if (
+      !tokenUsername ||
+      !cam?.company_id ||
+      !cam.cam_id ||
+      !streamIdentityEndpoint
+    )
       return "";
 
     // token 갱신 시각은 제외해 같은 카메라 stream family를 하나의 identity로 묶는다.
-    return [tokenUsername, cam.company_id, cam.cam_id, endpoint].join("|");
+    return [
+      tokenUsername,
+      cam.company_id,
+      cam.cam_id,
+      streamIdentityEndpoint,
+    ].join("|");
   })();
   const hasCurrentStreamState = streamStateIdentityKey === streamIdentityKey;
   const connectionState = hasCurrentStreamState ? connectionStateValue : "new";
@@ -289,9 +301,25 @@ export function useCctvRtcStream({
   const isTokenEndpointMissing = isStreamStartGranted && !tokenEndpointUrl;
   const isTokenError = tokenQuery.isError || isTokenEndpointMissing;
 
+  // token-specific ref는 실제 WHEP 요청 URL에만 붙이고 stream identity/key에서는 제외한다.
+  const requestEndpoint = (() => {
+    if (!streamIdentityEndpoint || !tokenQuery.data?.session_ref)
+      return undefined;
+
+    const nextEndpoint = new URL(streamIdentityEndpoint);
+    nextEndpoint.searchParams.set("session_ref", tokenQuery.data.session_ref);
+
+    return nextEndpoint.toString();
+  })();
+
   const streamKeyCandidate = (() => {
     // streamKey는 online 카메라와 endpoint/token이 모두 준비된 뒤에만 만들 수 있다.
-    if (!cam?.cam_id || !cam.cam_online || !endpoint || !tokenQuery.data?.token)
+    if (
+      !cam?.cam_id ||
+      !cam.cam_online ||
+      !streamIdentityEndpoint ||
+      !tokenQuery.data?.token
+    )
       return "";
 
     // token dataUpdatedAt을 포함해 명시 refetch 후에는 새 WHEP 연결 후보로 분리한다.
@@ -299,7 +327,7 @@ export function useCctvRtcStream({
       tokenUsername,
       cam.company_id,
       cam.cam_id,
-      endpoint,
+      streamIdentityEndpoint,
       tokenQuery.dataUpdatedAt,
     ].join("|");
   })();
@@ -466,7 +494,12 @@ export function useCctvRtcStream({
     }
 
     // 필수 값이 없으면 스트림을 시작하지 않는다.
-    if (!streamKey || !tokenQuery.data?.token || !endpoint || !currentVideo)
+    if (
+      !streamKey ||
+      !tokenQuery.data?.token ||
+      !requestEndpoint ||
+      !currentVideo
+    )
       return;
 
     // 같은 identity에서 token dataUpdatedAt만 바뀌면 새 stream attach 이후 이전 stream을 닫는다.
@@ -497,7 +530,7 @@ export function useCctvRtcStream({
     streamRegistry.start({
       streamKey,
       identityKey: streamIdentityKey,
-      endpoint,
+      endpoint: requestEndpoint,
       token: tokenQuery.data.token,
       video: currentVideo,
     });
@@ -545,7 +578,7 @@ export function useCctvRtcStream({
       detachVideo();
     };
   }, [
-    endpoint,
+    requestEndpoint,
     streamIdentityKey,
     streamKey,
     streamRegistry,

package/src/cctv/types/api.ts

@@ -144,7 +144,7 @@ export interface API_Res_CctvCameraData
  * CCTV: 업체에 설치된 카메라 목록
  * @property {string} cam_id 카메라 id코드
  * @property {string} cam_name 카메라 별칭
- * @property {boolean} cam_online 카메라 설치상태
+ * @property {boolean} cam_online 카메라 네트워크 연결 상태
  * @property {string} cam_rtc 카메라 스트리밍 WebRTC 경로
  * @property {string} cam_rtcp 카메라 RTCP 경로
  * @property {string} cam_rtsp 카메라 RTSP 경로
@@ -156,7 +156,7 @@ export interface API_Res_CctvCameraData
 export interface API_Res_CctvCompanyCameraList extends API_Res_CctvCameraData {
   // API 응답은 데이터-only 구조이므로 UI 전용 콜백은 포함하지 않는다.
   /**
-   * 카메라 설치 상태
+   * 카메라 네트워크 연결 상태
    */
   cam_online: boolean;
 }
@@ -316,6 +316,7 @@ export interface API_Req_CctvRtcToken {
 /**
  * CCTV; 실시간 스트리밍 토큰 응답
  * @property {string} token 인증 토큰
+ * @property {string} session_ref WHEP 세션 연계용 단기 참조값
  */
 export interface API_Res_CctvRtcToken {
   /**
@@ -323,6 +324,10 @@ export interface API_Res_CctvRtcToken {
    * Bearer
    */
   token: string;
+  /**
+   * WHEP 요청 세션 연계용 단기 참조값
+   */
+  session_ref: string;
 }
 
 /**

package/src/cctv/types/hook.ts

@@ -195,7 +195,7 @@ export interface UseCctvCompanyDataReturn extends Omit<
  * @property {CctvCompanyGroupItems | undefined} selectedCompany 선택된 업체 데이터
  * @property {CctvCompanyCameraData | undefined} selectedCam 선택된 카메라 데이터
  * @property {CctvCompanyGroup[]} groups 업체 그룹/업체/카메라 리스트 구조 데이터
- * @property {string[]} companyValidList 온라인 카메라가 하나라도 있는 업체 ID 리스트
+ * @property {string[]} companyValidList 카메라가 하나라도 있는 업체 ID 리스트
  * @property {CctvCompanyCameraList[]} cams 선택된 업체의 카메라 리스트
  * @property {number} liveCamCount 실시간 스트리밍 중인 카메라 수
  * @property {(cam_id: string) => void} onToggleCamera 카메라 선택 토글 함수
@@ -244,7 +244,7 @@ export interface UseCctvContextReturn extends UseFormReturn<CctvBaseContext> {
    */
   groups: CctvCompanyGroup[];
   /**
-   * 스트리밍이 가능한 업체 목록
+   * 카메라가 하나라도 있는 업체 목록
    */
   companyValidList: string[];
   /**

package/src/cctv/types/list.ts

@@ -10,7 +10,7 @@ import type {
  * @property {Function} [onSelect] 카메라 선택 콜백 이벤트
  * @property {string} cam_id 카메라 id코드
  * @property {string} cam_name 카메라 별칭
- * @property {boolean} cam_online 카메라 설치상태
+ * @property {boolean} cam_online 카메라 네트워크 연결 상태
  * @property {string} [cam_rtc] 카메라 스트리밍 WebRTC 경로
  * @property {string} [cam_rtcp] 카메라 RTCP 경로
  * @property {string} [cam_rtsp] 카메라 RTSP 경로
@@ -46,7 +46,7 @@ export interface CctvCompanyCameraData extends API_Res_CctvCompanyCameraList {
  * @property {Function} [onSelect] 카메라 선택 콜백 이벤트
  * @property {string} cam_id 카메라 id코드
  * @property {string} cam_name 카메라 별칭
- * @property {boolean} cam_online 카메라 설치상태
+ * @property {boolean} cam_online 카메라 네트워크 연결 상태
  * @property {string} [cam_rtc] 카메라 스트리밍 WebRTC 경로
  * @property {string} [cam_rtcp] 카메라 RTCP 경로
  * @property {string} [cam_rtsp] 카메라 RTSP 경로

package/src/cctv/utils/video-state.ts

@@ -13,6 +13,7 @@ export const CCTV_MESSAGE = {
     "장시간 미사용으로 연결이 종료되었습니다. 계속 확인하시려면 다시 연결해 주세요.",
   tokenError: "토큰을 발급하지 못했습니다.",
   offline: "CCTV 연결 오류",
+  networkDisconnected: "네트워크 연결이 끊어졌습니다.",
 } as const;
 
 const RTC_PREPARING_STATES = new Set<RTCPeerConnectionState>([
@@ -56,7 +57,7 @@ export function getOverlayMessage({
     return isFetching ? CCTV_MESSAGE.fetching : CCTV_MESSAGE.selectCam;
   }
 
-  if (!cam.cam_online) return CCTV_MESSAGE.offline;
+  if (!cam.cam_online) return CCTV_MESSAGE.networkDisconnected;
   // 에러 상태가 준비 상태와 겹칠 때는 에러 문구가 최종 표시 계약을 우선한다.
   if (isTokenError) return CCTV_MESSAGE.tokenError;
   if (streamError) return streamError;