@uniai-fe/uds-templates 0.10.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "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",
@@ -69,15 +69,15 @@
     "typescript": "6.0.3",
     "@uniai-fe/eslint-config": "0.4.0",
     "@uniai-fe/next-devkit": "0.4.0",
-    "@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/tsconfig": "0.2.0",
     "@uniai-fe/uds-foundation": "0.5.0",
-    "@uniai-fe/util-jotai": "0.3.0",
     "@uniai-fe/util-api": "0.2.1",
+    "@uniai-fe/util-functions": "0.4.1",
+    "@uniai-fe/util-jotai": "0.3.0",
     "@uniai-fe/util-next": "0.5.0",
-    "@uniai-fe/util-rtc": "0.2.0"
+    "@uniai-fe/util-rtc": "0.2.0",
+    "@uniai-fe/uds-primitives": "0.10.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/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

@@ -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;
 }
 
 /**