@uniai-fe/uds-templates 0.6.25 → 0.6.27

package/src/cctv/types/api.ts

@@ -1,5 +1,4 @@
 import type { API_Res_Base } from "@uniai-fe/util-api";
-import type { NextRequest } from "next/server";
 
 /**
  * CCTV; api getCompanyList params
@@ -298,7 +297,6 @@ export type API_Res_CctvCompany = API_Res_Base<API_Res_CctvCompanyData>;
  * @property {string} company_id 업체 id코드
  * @property {string} cam_id 카메라 id코드
  * @property {string} username 사용자 계정 아이디
- * @property {string} [password] 사용자 계정 비밀번호. 생략 시 서버 route에서 tokenPreset.password 또는 username fallback을 사용
  */
 export interface API_Req_CctvRtcToken {
   /**
@@ -313,54 +311,6 @@ export interface API_Req_CctvRtcToken {
    * 사용자 계정 아이디
    */
   username: string;
-  /**
-   * 사용자 계정 비밀번호
-   * - 서버 route에서 tokenPreset.password 또는 username fallback을 사용하는 경우 생략 가능
-   */
-  password?: string;
-}
-
-/**
- * CCTV; 실시간 스트리밍 토큰 요청 (백엔드 요청)
- * @property {string} site company_id 맵핑 (ex. farm102)
- * @property {string} username 사용자 계정 아이디
- * @property {string} password 사용자 계정 비밀번호
- * @property {string} action "read"
- * @property {string} path cam_id 맵핑 (ex. cam3)
- * @property {number} ttl_seconds 시간? (default 300)
- * @property {string} kid "streaming-auth-1"
- */
-export interface API_Req_CctvRtcTokenOrigin {
-  /**
-   * company_id 맵핑
-   * ex) farm102
-   */
-  site: string;
-  /**
-   * 사용자 계정 아이디
-   */
-  username: string;
-  /**
-   * 사용자 계정 비밀번호
-   */
-  password: string;
-  /**
-   * "read"
-   */
-  action: string;
-  /**
-   * cam_id 맵핑
-   * ex) cam3
-   */
-  path: string;
-  /**
-   * default) 300
-   */
-  ttl_seconds: number;
-  /**
-   * "streaming-auth-1"
-   */
-  kid: string;
 }
 
 /**
@@ -411,47 +361,3 @@ export interface API_Req_CctvStreamToken {
    */
   cam_id: string;
 }
-
-/**
- * CCTV; 서버 토큰 요청 파라미터
- * @property {string} domain API 요청 도메인(서버)
- * @property {string} routeUrl Next.js app/api 이하 경로 url
- * @property {string} [queryUrl] 백엔드 요청 url
- * @property {string} username 사용자 아이디
- * @property {string} company_id 업체 id코드(site)
- * @property {string} cam_id 카메라 id코드
- * @property {string} [password] 서버 route에서 주입할 사용자 비밀번호
- * @property {number} [ttl_seconds] 토큰 만료시간
- * @property {string} [kid] 키 id
- * @property {Record<string, string>} [headers] 추가 요청 헤더
- */
-export type API_Req_CctvTokenPreset = Partial<
-  Pick<API_Req_CctvRtcTokenOrigin, "password" | "ttl_seconds" | "kid">
->;
-
-export interface API_Req_GetCctvTokenParams {
-  /**
-   * API 도메인
-   */
-  domain: string;
-  /**
-   * Next.js /app/api 라우트 주소
-   */
-  routeUrl: string;
-  /**
-   * 백엔드 요청 url
-   */
-  queryUrl?: string;
-  /**
-   * Next.js API 요청 body
-   */
-  req: NextRequest;
-  /**
-   * 추가 요청 헤더
-   */
-  headers?: Record<string, string>;
-  /**
-   * 서버 route에서 주입할 CCTV 토큰 요청 preset
-   */
-  tokenPreset?: API_Req_CctvTokenPreset;
-}

package/src/cctv/types/context.ts

@@ -55,6 +55,22 @@ export interface CctvApiUrlContext {
   tokenUrl?: string;
 }
 
+/**
+ * CCTV; RTC stream lazy loading 옵션
+ * @property {number} [batchSize] 한 번에 token/WHEP 시작 권한을 받을 stream 개수 (default: 4)
+ * @property {number} [batchIntervalMs] 다음 batch 시작까지 대기할 시간(ms) (default: 1200)
+ */
+export interface CctvRtcStreamOptions {
+  /**
+   * 한 번에 token/WHEP 시작 권한을 받을 stream 개수
+   */
+  batchSize?: number;
+  /**
+   * 다음 batch 시작까지 대기할 시간(ms)
+   */
+  batchIntervalMs?: number;
+}
+
 /**
  * CCTV; 실시간 영상보기 컨텍스트
  * @property {string} [company_id] 선택된 업체 id코드
@@ -125,6 +141,7 @@ export type CctvContext<ContextExtension extends object = object> =
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
  * @property {string} [whepUsername] WHEP endpoint username 덮어쓰기 값
  * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
+ * @property {CctvRtcStreamOptions} [streamOptions] stream lazy loading 옵션
  * @property {React.ReactNode} children
  */
 export type CctvProviderProps<ContextExtension extends object = object> =
@@ -142,6 +159,10 @@ export type CctvProviderProps<ContextExtension extends object = object> =
        * 서비스 확장 context 기본값
        */
       defaultValues?: ContextExtension;
+      /**
+       * stream lazy loading 옵션
+       */
+      streamOptions?: CctvRtcStreamOptions;
       /**
        * Provider 하위 콘텐츠
        */

package/src/cctv/types/hook.ts

@@ -20,6 +20,24 @@ export type CctvRtcReconnectTrigger = (
   options?: RefetchOptions,
 ) => Promise<QueryObserverResult<API_Res_CctvRtcToken>>;
 
+/**
+ * CCTV; RTC stream scheduler 상태
+ */
+export type CctvRtcStreamScheduleStatus = "idle" | "queued" | "granted";
+
+/**
+ * CCTV; RTC stream 표시 단계
+ */
+export type CctvRtcStreamStage =
+  | "idle"
+  | "queued"
+  | "token-loading"
+  | "connecting"
+  | "live"
+  | "recovering"
+  | "error"
+  | "skipped-offline";
+
 /**
  * CCTV; useCctvRtcStream params
  * @property {CctvCompanyCameraData} [cam] 스트리밍 카메라 정보
@@ -64,6 +82,7 @@ export interface UseCctvRtcStreamError {
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {CctvRtcStreamStage} streamStage stream 표시 단계
  */
 export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
   /**
@@ -88,6 +107,10 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
    * 재발급 중에는 기존 화면과 live count를 유지하기 위해 false로 smoothing될 수 있다.
    */
   isTokenLoading: boolean;
+  /**
+   * stream 표시 단계
+   */
+  streamStage: CctvRtcStreamStage;
 }
 
 /**
@@ -98,6 +121,7 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
+ * @property {CctvRtcStreamStage} streamStage stream 표시 단계
  * @property {boolean} canReconnect UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
  * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수

package/src/cctv/types/props.ts

@@ -1,5 +1,5 @@
 import type { CctvCompanyCameraData, CctvCompanyCameraList } from "./list";
-import type { CctvRtcReconnectTrigger } from "./hook";
+import type { CctvRtcReconnectTrigger, CctvRtcStreamStage } from "./hook";
 
 /**
  * CCTV; custom overlay render context
@@ -9,6 +9,7 @@ import type { CctvRtcReconnectTrigger } from "./hook";
  * @property {boolean | undefined} [isError] 영상 에러 상태 여부
  * @property {boolean | undefined} [isLive] 영상 live 상태 여부
  * @property {React.ReactNode} [overlayMessage] 기본 안내/에러 메시지 콘텐츠
+ * @property {CctvRtcStreamStage | undefined} [streamStage] stream 표시 단계
  * @property {boolean | undefined} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger | undefined} [reconnectStream] 재연결 trigger 함수
  */
@@ -37,6 +38,10 @@ export interface CctvVideoRenderOverlayContext {
    * 기본 안내/에러 메시지 콘텐츠
    */
   overlayMessage?: React.ReactNode;
+  /**
+   * stream 표시 단계
+   */
+  streamStage?: CctvRtcStreamStage;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    * @desc
@@ -130,6 +135,7 @@ export interface CctvVideoOverlayFooterProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
+ * @property {CctvRtcStreamStage} [streamStage] stream 표시 단계
  * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger} [reconnectStream] 재연결 trigger 함수
  */
@@ -146,6 +152,10 @@ export interface CctvVideoStateProps {
    * 오버레이 메시지 콘텐츠
    */
   overlayMessage?: React.ReactNode;
+  /**
+   * stream 표시 단계
+   */
+  streamStage?: CctvRtcStreamStage;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
@@ -164,6 +174,7 @@ export interface CctvVideoStateProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
+ * @property {CctvRtcStreamStage} [streamStage] stream 표시 단계
  * @property {CctvVideoRenderOverlay} [renderOverlay] custom overlay 렌더 함수
  */
 export interface CctvVideoTemplateProps extends CctvVideoStateProps {

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

@@ -1,5 +1,9 @@
 import type { CctvCompanyCameraData } from "./list";
-import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
+import type {
+  CctvRtcStreamStage,
+  UseCctvRtcStreamError,
+  UseCctvRtcStreamState,
+} from "./hook";
 
 /**
  * CCTV; getOverlayMessage() params
@@ -11,10 +15,14 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {CctvRtcStreamStage} [streamStage] stream 표시 단계
  * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부.
  * 오류 스타일 판정에는 직접 사용하지 않는다.
  */
-export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
+export interface CctvVideoOverlayMessageParams extends Omit<
+  UseCctvRtcStreamState,
+  "streamStage"
+> {
   /**
    * 카메라 데이터
    */
@@ -27,6 +35,10 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
    * 서버에서 cam 리스트를 가져오는 중인지 여부
    */
   isFetching?: boolean;
+  /**
+   * stream 표시 단계
+   */
+  streamStage?: CctvRtcStreamStage;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    * @desc
@@ -44,7 +56,10 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  */
-export interface CctvVideoLiveParams extends UseCctvRtcStreamState {
+export interface CctvVideoLiveParams extends Omit<
+  UseCctvRtcStreamState,
+  "streamStage"
+> {
   /**
    * 카메라 데이터
    */

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

@@ -7,6 +7,7 @@ import type {
 export const CCTV_MESSAGE = {
   selectCam: "카메라를 선택하세요.",
   fetching: "CCTV 데이터를 불러오는 중입니다.",
+  queued: "CCTV 연결 순서를 기다리고 있습니다.",
   preparing: "CCTV 영상을 연결하고 있습니다.",
   sessionEnded:
     "장시간 미사용으로 연결이 종료되었습니다. 계속 확인하시려면 다시 연결해 주세요.",
@@ -47,6 +48,7 @@ export function getOverlayMessage({
   isTokenLoading,
   isTokenError,
   isStreaming,
+  streamStage,
   streamError,
 }: CctvVideoOverlayMessageParams): string | null {
   if (!cam) {
@@ -62,6 +64,7 @@ export function getOverlayMessage({
   if (canReconnect && RTC_SESSION_ENDED_RECONNECT_STATES.has(connectionState)) {
     return CCTV_MESSAGE.sessionEnded;
   }
+  if (streamStage === "queued") return CCTV_MESSAGE.queued;
   // raw disconnected는 useCctvRtcStream에서 post-connected connected로 smoothing한다.
   if (isTokenLoading || isStreaming) return CCTV_MESSAGE.preparing;
   if (RTC_PREPARING_STATES.has(connectionState)) return CCTV_MESSAGE.preparing;