@nowsoft-lab/chear-widget-react 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# @nowsoft-lab/chear-widget-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@nowsoft-lab/chear-widget-react)](https://www.npmjs.com/package/@nowsoft-lab/chear-widget-react)
+![react](https://img.shields.io/badge/react-%E2%89%A518-61dafb)
+
+치어(CHEAR) 라이브 방송의 **플레이어**와 **채팅**을 리액트 앱에 컴포넌트로 넣습니다.
+채널 아이디 하나만 넘기면 스튜디오 › 위젯과 **같은 화면 · 같은 동작**이 나오고, 위젯이 개선되면 이 패키지를 다시 설치하지 않아도 같이 바뀝니다.
+
+```tsx
+import { ChearPlayer, ChearChat } from "@nowsoft-lab/chear-widget-react";
+
+export default function Live() {
+  return (
+    <div style={{ display: "flex", gap: 16 }}>
+      <ChearPlayer channel="streamer01" style={{ flex: 1 }} />
+      <ChearChat channel="streamer01" style={{ width: 360, height: 600 }} />
+    </div>
+  );
+}
+```
+
+- API 키 · 백엔드 연동 없이 바로 씁니다.
+- 방송 중이면 재생, 아니면 채널 프로필과 "방송 준비 중"을 보여 줍니다. 방송이 시작되면 저절로 재생으로 바뀝니다.
+- 채팅은 읽기만이 아니라 **실제로 채팅**합니다 — 로그인 · 가입 · 이모티콘 · 신고 · 팔로우가 위젯 안에서 됩니다.
+- 위젯은 Shadow DOM 안에 그려져 내 사이트 스타일과 서로 섞이지 않습니다.
+
+## 설치
+
+```sh
+npm i @nowsoft-lab/chear-widget-react
+# 또는
+pnpm add @nowsoft-lab/chear-widget-react
+yarn add @nowsoft-lab/chear-widget-react
+```
+
+- React 18 이상(18 · 19).
+- ES 모듈만 제공합니다(Vite · Next.js · webpack 5 · Rspack 등 요즘 번들러는 그대로 됩니다).
+- 타입(TypeScript) 포함.
+
+## 컴포넌트
+
+### `<ChearPlayer>` — 방송 플레이어
+
+```tsx
+<ChearPlayer channel="streamer01" />
+<ChearPlayer channel="streamer01" chat />                  {/* 오른쪽에 채팅 같이 */}
+<ChearPlayer channel="streamer01" muted={false} autoplay={false} />
+```
+
+| prop | 타입 | 기본 | 설명 |
+|---|---|---|---|
+| `channel` | `string` | **필수** | 채널 아이디(스튜디오에 보이는 @아이디) |
+| `autoplay` | `boolean` | `true` | 자동 재생. 브라우저 정책상 소리 끔과 함께일 때만 확실합니다 |
+| `muted` | `boolean` | `true` | 소리 끔으로 시작. 화면의 "소리 켜기"로 켤 수 있습니다 |
+| `controls` | `boolean` | `true` | 재생 컨트롤 표시 |
+| `chat` | `boolean` | `false` | 플레이어 오른쪽에 채팅을 같이(좁은 세로 화면은 아래). 컨트롤의 채팅 단추로 접고 펼칩니다 |
+| `stats` | `boolean` | `true` | 왼쪽 위 LIVE · 시청 중 표시 |
+
+**크기** — 기본은 부모 폭 100% · 16:9 입니다. 폭만 정하면 높이는 따라옵니다.
+
+```tsx
+<ChearPlayer channel="streamer01" style={{ width: 640 }} />          {/* 640 × 360 */}
+<ChearPlayer channel="streamer01" className="my-player" />           {/* CSS 로 */}
+```
+
+### `<ChearChat>` — 채팅
+
+```tsx
+<ChearChat channel="streamer01" style={{ width: 360, height: 600 }} />
+<ChearChat channel="streamer01" theme="light" />
+```
+
+| prop | 타입 | 기본 | 설명 |
+|---|---|---|---|
+| `channel` | `string` | **필수** | 채널 아이디 |
+| `theme` | `"dark" \| "light"` | `"dark"` | 다크 · 라이트 |
+
+**크기** — 기본은 폭 100% · 부모 높이(부모에 높이가 없으면 최소 480px). 높이를 꼭 정해 주세요.
+
+### 공통 prop
+
+| prop | 타입 | 설명 |
+|---|---|---|
+| `ssoToken` | `string` | 간편 로그인(SSO) 토큰 — 내 사이트 회원을 바로 채팅에 로그인시킵니다. [아래](#간편-로그인sso) |
+| `origin` | `string` | 위젯 출처. 기본 `https://player.chear.live`. 보통은 안 넣습니다 |
+| `className` · `style` | | 위젯 바깥 div 에 그대로 |
+| `onError` | `(error) => void` | 위젯을 불러오지 못했을 때(네트워크 · 사이트 보안 정책) |
+
+### `<ChearProvider>` — 위젯 출처 한 번에
+
+개발서버나 다른 플랫폼 위젯을 쓸 때만 필요합니다.
+
+```tsx
+import { ChearProvider, ChearPlayer, ChearChat } from "@nowsoft-lab/chear-widget-react";
+
+<ChearProvider origin="https://dev.chear.live">
+  <ChearPlayer channel="streamer01" />
+  <ChearChat channel="streamer01" />
+</ChearProvider>
+```
+
+## Next.js
+
+App Router 에서 그대로 씁니다. 패키지에 `"use client"` 가 들어 있어 서버 컴포넌트에서 바로 import 해도 됩니다 — 서버에서는 빈 div 만 그리고, 브라우저에서 위젯이 뜹니다.
+
+```tsx
+// app/live/page.tsx
+import { ChearPlayer } from "@nowsoft-lab/chear-widget-react";
+
+export default function Page() {
+  return <ChearPlayer channel="streamer01" />;
+}
+```
+
+## 간편 로그인(SSO)
+
+내 사이트에 로그인한 회원을 치어 계정 없이 바로 채팅에 들어오게 합니다(치어에서 파트너 SSO 를 켠 경우).
+**내 서버**에서 SSO 비밀값으로 짧은 토큰(JWT HS256, 5분 이하)을 만들어 컴포넌트에 넘깁니다 — 비밀값은 브라우저에 두지 마세요.
+
+```tsx
+const { token } = await fetch("/my-api/chear-sso").then((r) => r.json()); // 내 서버가 만든 토큰
+<ChearChat channel="streamer01" ssoToken={token} />
+```
+
+- 토큰 형식(claims) · 서버 예제(Node · PHP · Java) · 오류 코드: 스튜디오 › 위젯 › 채팅 › "간편 로그인 안내" 또는 [개발자 문서](https://www.chear.live/developers/api).
+- 토큰은 한 번만 쓸 수 있습니다. 새 토큰을 넘기면 위젯이 다시 로그인합니다.
+
+## 내 사이트 설정
+
+### 허용 도메인
+
+채널 설정에 "허용 도메인"이 있으면 **그 사이트에서만 로그인 · 채팅**할 수 있습니다(아니면 로그인 때 `EMB-005`). 보기 · 재생은 막지 않습니다.
+채널 설정에서 "퍼가기 허용"을 끄면 어디서든 안내만 나옵니다.
+
+### CSP(Content-Security-Policy)
+
+사이트에 CSP 를 쓰고 있다면 아래를 더해 주세요.
+
+| 지시어 | 넣을 주소 |
+|---|---|
+| `script-src` | `https://player.chear.live` |
+| `connect-src` | `https://player.chear.live` `https://*.edge.naverncp.com` `https://*.firebasedatabase.app` `wss://*.firebasedatabase.app` `https://firestore.googleapis.com` `https://identitytoolkit.googleapis.com` `https://securetoken.googleapis.com` |
+| `media-src` | `blob:` `https://*.edge.naverncp.com` |
+| `img-src` | `https://*.edge.naverncp.com` `data:` |
+| `style-src` | `https://cdn.jsdelivr.net` `'unsafe-inline'` |
+| `font-src` | `https://cdn.jsdelivr.net` |
+
+`ChearProvider` 로 다른 출처를 쓰면 `player.chear.live` 자리에 그 출처를 넣습니다.
+
+### 브라우저 저장소
+
+채팅 로그인 정보는 이 사이트의 `localStorage` 에 `chear.widget:` 로 시작하는 키로 둡니다. 채팅 · 신고 · 팔로우만 되는 짧은 토큰이고, 결제 · 마이페이지 같은 권한은 없습니다.
+사이트 스크립트와 완전히 떼어 두어야 한다면 스튜디오 › 위젯의 **iframe 위젯**을 쓰세요.
+
+## 동작 방식
+
+이 패키지는 얇은 껍데기입니다. 화면은 위젯 출처의 런타임(`https://player.chear.live/sdk/v1/runtime.js`)이 그립니다.
+
+1. 컴포넌트가 처음 그려질 때 런타임을 한 번 받습니다(브라우저 캐시 · 여러 컴포넌트가 함께 씀).
+2. 컴포넌트의 div 에 Shadow DOM 을 열고 그 안에 위젯을 그립니다. 모달 · 로그인 창 · 전체 화면도 위젯 틀 안에서만 동작합니다.
+3. prop 이 바뀌면 다시 받지 않고 그 자리에서 바뀝니다.
+
+그래서 화면 · 기능 개선은 런타임 배포만으로 모든 사이트에 반영됩니다. 이 패키지의 판은 prop 이 바뀔 때만 올라갑니다.
+
+## 판 정책
+
+| 판 | 런타임 | |
+|---|---|---|
+| 1.x | `/sdk/v1/` | 지금. prop 추가는 1.x 안에서(기존 코드 그대로 동작) |
+| 2.x | `/sdk/v2/` | prop 을 바꾸거나 빼는 큰 변경일 때만. 1.x 는 한동안 함께 유지 |
+
+## 문제 해결
+
+| 증상 | 확인할 것 |
+|---|---|
+| 아무것도 안 보임 | `onError` 로 오류 확인. 사이트 CSP 의 `script-src` · 광고 차단 확장 |
+| "이 채널은 퍼가기를 허용하지 않아요" | 채널 설정의 퍼가기 허용 |
+| 로그인하면 `EMB-005` | 채널 허용 도메인에 내 사이트 도메인 추가 |
+| 채팅 높이가 0 · 너무 작음 | `<ChearChat>` 또는 부모에 높이 지정 |
+| 소리가 안 나옴 | 자동 재생은 소리 끔으로 시작합니다. 화면의 "소리 켜기" 또는 `muted={false}`(브라우저가 막으면 소리 끔으로 재생) |
+
+## 라이선스
+
+UNLICENSED — 치어 위젯을 넣는 용도로만 씁니다.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { ChatOptions, PlayerOptions } from "./types";
+export { DEFAULT_ORIGIN, loadRuntime, runtimeUrl } from "./loader";
+export type { ChatOptions, PlayerOptions } from "./types";
+/** 위젯 출처를 바꿀 때만(개발서버 · 다른 플랫폼). 운영 치어는 필요 없음 */
+export declare function ChearProvider({ origin, children }: {
+    origin: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+interface CommonProps {
+    /** 채널 아이디 — 스튜디오에 보이는 @아이디(위젯 주소의 /embed/{아이디}/…) */
+    channel: string;
+    /** 간편 로그인(SSO) 토큰 — 파트너 회원으로 바로 채팅. 없으면 위젯 안 로그인 */
+    ssoToken?: string;
+    /** 위젯 출처 — ChearProvider 보다 우선 */
+    origin?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** 런타임을 못 불러왔을 때(네트워크 · 사이트 CSP 등) */
+    onError?: (error: unknown) => void;
+}
+export type ChearPlayerProps = CommonProps & PlayerOptions;
+export type ChearChatProps = CommonProps & ChatOptions;
+/** 플레이어 — 기본 폭 100% · 16:9. `chat` 이면 오른쪽에 채팅 같이 */
+export declare function ChearPlayer({ autoplay, muted, controls, chat, stats, ...common }: ChearPlayerProps): import("react").JSX.Element;
+/** 채팅 — 실제로 채팅(위젯 안 로그인 · 이모티콘 · 신고). 기본 폭 100% · 부모 높이(없으면 최소 480px) */
+export declare function ChearChat({ theme, ...common }: ChearChatProps): import("react").JSX.Element;

package/dist/index.js

@@ -0,0 +1,66 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { DEFAULT_ORIGIN, loadRuntime } from "./loader";
+export { DEFAULT_ORIGIN, loadRuntime, runtimeUrl } from "./loader";
+/**
+ * 치어 위젯 — 플레이어 · 채팅을 리액트 컴포넌트로 (docs/design/embed-sdk.md).
+ * 화면은 위젯 출처의 런타임(`/sdk/v1/runtime.js`)이 그린다 — 스튜디오 › 위젯의 iframe 위젯과 같은 화면 · 같은 동작.
+ * 파트너 페이지 스타일과 섞이지 않게 컴포넌트의 div 안 Shadow DOM 에 그린다.
+ */
+const OriginContext = createContext(DEFAULT_ORIGIN);
+/** 위젯 출처를 바꿀 때만(개발서버 · 다른 플랫폼). 운영 치어는 필요 없음 */
+export function ChearProvider({ origin, children }) {
+    return _jsx(OriginContext.Provider, { value: origin, children: children });
+}
+/** 정의된 값만 — 없는 옵션은 위젯 기본값 */
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+function Widget({ kind, channel, ssoToken, origin, className, style, onError, options, defaultStyle }) {
+    const fromContext = useContext(OriginContext);
+    const target = origin ?? fromContext;
+    const host = useRef(null);
+    const instance = useRef(null);
+    const [failed, setFailed] = useState(false);
+    const config = { kind, channel, options: defined(options), ssoToken };
+    const latest = useRef(config);
+    latest.current = config;
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
+    // 출처마다 한 번 그린다 — 옵션 · 채널이 바뀌면 아래 update 로
+    useEffect(() => {
+        const el = host.current;
+        if (!el)
+            return;
+        let cancelled = false;
+        setFailed(false);
+        loadRuntime(target).then((runtime) => {
+            if (!cancelled)
+                instance.current = runtime.mount(el, latest.current);
+        }, (error) => {
+            if (cancelled)
+                return;
+            setFailed(true);
+            onErrorRef.current?.(error);
+        });
+        return () => {
+            cancelled = true;
+            instance.current?.unmount();
+            instance.current = null;
+        };
+    }, [target]);
+    const key = JSON.stringify(config);
+    useEffect(() => {
+        instance.current?.update(latest.current);
+    }, [key]);
+    return _jsx("div", { ref: host, className: className, style: { ...defaultStyle, ...style }, "data-chear-widget": kind, "data-failed": failed || undefined });
+}
+/** 플레이어 — 기본 폭 100% · 16:9. `chat` 이면 오른쪽에 채팅 같이 */
+export function ChearPlayer({ autoplay, muted, controls, chat, stats, ...common }) {
+    return _jsx(Widget, { kind: "player", options: { autoplay, muted, controls, chat, stats }, defaultStyle: { display: "block", width: "100%", aspectRatio: "16 / 9" }, ...common });
+}
+/** 채팅 — 실제로 채팅(위젯 안 로그인 · 이모티콘 · 신고). 기본 폭 100% · 부모 높이(없으면 최소 480px) */
+export function ChearChat({ theme, ...common }) {
+    return _jsx(Widget, { kind: "chat", options: { theme }, defaultStyle: { display: "block", width: "100%", height: "100%", minHeight: 480 }, ...common });
+}

package/dist/loader.d.ts

@@ -0,0 +1,13 @@
+import type { WidgetRuntime } from "./types";
+/** 운영 위젯 출처 — 개발 · 다른 플랫폼은 <ChearProvider origin="…"> */
+export declare const DEFAULT_ORIGIN = "https://player.chear.live";
+/** 런타임 판 — 위젯 출처의 /sdk/v{N}/runtime.js */
+export declare const RUNTIME_VERSION = 1;
+/** `https://player.chear.live/` · 경로가 붙은 주소 → 출처만 */
+export declare function normalizeOrigin(origin: string): string;
+export declare const runtimeUrl: (origin: string) => string;
+/**
+ * 런타임을 위젯 출처에서 한 번만 받는다(같은 출처면 컴포넌트 여러 개가 같이 씀).
+ * 화면은 런타임에 있어서 위젯이 바뀌면 이 패키지를 다시 받지 않아도 같이 바뀐다. 실패하면 다음 시도 때 다시 받는다
+ */
+export declare function loadRuntime(origin?: string): Promise<WidgetRuntime>;

package/dist/loader.js

@@ -0,0 +1,32 @@
+/** 운영 위젯 출처 — 개발 · 다른 플랫폼은 <ChearProvider origin="…"> */
+export const DEFAULT_ORIGIN = "https://player.chear.live";
+/** 런타임 판 — 위젯 출처의 /sdk/v{N}/runtime.js */
+export const RUNTIME_VERSION = 1;
+/** `https://player.chear.live/` · 경로가 붙은 주소 → 출처만 */
+export function normalizeOrigin(origin) {
+    return new URL(origin).origin;
+}
+export const runtimeUrl = (origin) => `${normalizeOrigin(origin)}/sdk/v${RUNTIME_VERSION}/runtime.js`;
+const loading = new Map();
+/**
+ * 런타임을 위젯 출처에서 한 번만 받는다(같은 출처면 컴포넌트 여러 개가 같이 씀).
+ * 화면은 런타임에 있어서 위젯이 바뀌면 이 패키지를 다시 받지 않아도 같이 바뀐다. 실패하면 다음 시도 때 다시 받는다
+ */
+export function loadRuntime(origin = DEFAULT_ORIGIN) {
+    const url = runtimeUrl(origin);
+    let pending = loading.get(url);
+    if (!pending) {
+        // 런타임 조각들이 실행되기 전에 "위젯 SDK 로 돈다 · 위젯 출처"를 알린다(런타임이 파트너 문서의 <html> 을 건드리지 않게)
+        const g = globalThis;
+        g.__CHEAR_SDK__ ?? (g.__CHEAR_SDK__ = { origin: normalizeOrigin(origin) });
+        pending = import(/* @vite-ignore */ /* webpackIgnore: true */ url).then((mod) => {
+            const runtime = mod.default;
+            if (!runtime || runtime.version !== RUNTIME_VERSION)
+                throw new Error(`치어 위젯 런타임을 불러오지 못했어요(${url})`);
+            return runtime;
+        });
+        pending.catch(() => loading.delete(url));
+        loading.set(url, pending);
+    }
+    return pending;
+}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 위젯 런타임과의 약속(v1) — 런타임 쪽 같은 모양: user-web `src/sdk/types.ts`. 바꾸면 둘 다 같이(docs/design/embed-sdk.md 2장)
+ */
+/** 플레이어 옵션 — 위젯 주소 쿼리와 같은 이름 · 같은 기본값 */
+export interface PlayerOptions {
+    /** 자동 재생(기본 켬 — 브라우저 정책상 소리 끔과 함께만 확실) */
+    autoplay?: boolean;
+    /** 소리 끔(기본 켬) */
+    muted?: boolean;
+    /** 플레이어 컨트롤(기본 켬) */
+    controls?: boolean;
+    /** 오른쪽(좁은 세로 화면은 아래)에 채팅 같이(기본 끔) */
+    chat?: boolean;
+    /** 왼쪽 위 LIVE · 시청 중(기본 켬) */
+    stats?: boolean;
+}
+/** 채팅 옵션 */
+export interface ChatOptions {
+    /** 다크(기본) · 라이트 */
+    theme?: "dark" | "light";
+}
+export type WidgetKind = "player" | "chat";
+export interface WidgetConfig {
+    kind: WidgetKind;
+    channel: string;
+    options?: PlayerOptions | ChatOptions;
+    ssoToken?: string;
+}
+export interface WidgetInstance {
+    update(config: WidgetConfig): void;
+    unmount(): void;
+}
+export interface WidgetRuntime {
+    version: 1;
+    origin: string;
+    mount(host: HTMLElement, config: WidgetConfig): WidgetInstance;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * 위젯 런타임과의 약속(v1) — 런타임 쪽 같은 모양: user-web `src/sdk/types.ts`. 바꾸면 둘 다 같이(docs/design/embed-sdk.md 2장)
+ */
+export {};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@nowsoft-lab/chear-widget-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "치어(CHEAR) 위젯 — 플레이어 · 채팅을 리액트 컴포넌트로. <ChearPlayer channel=\"…\" />",
+  "keywords": [
+    "chear",
+    "react",
+    "live",
+    "streaming",
+    "player",
+    "chat",
+    "widget"
+  ],
+  "homepage": "https://www.chear.live/developers/api#widget-sdk",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "pack:sdk": "pnpm build && node scripts/pack-sdk.mjs",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "release": "bash scripts/publish.sh"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}