issue-sticker 0.1.0

package/LICENSE

@@ -0,0 +1,51 @@
+IssueSticker SDK Proprietary License
+
+Copyright (c) 2026 maana. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary property of maana. The Software is licensed, not sold.
+
+1. GRANT OF LICENSE
+   Subject to the terms of this license, maana grants you a limited,
+   non-exclusive, non-transferable, revocable license to use the Software
+   solely in connection with a valid IssueSticker API key obtained through
+   an active subscription.
+
+2. RESTRICTIONS
+   You may NOT:
+   (a) Copy, modify, merge, or create derivative works of the Software;
+   (b) Reverse engineer, decompile, disassemble, or otherwise attempt to
+       derive the source code of the Software;
+   (c) Redistribute, sublicense, rent, lease, or lend the Software to
+       any third party;
+   (d) Remove or alter any proprietary notices, labels, or marks on the
+       Software;
+   (e) Use the Software without a valid API key or in violation of the
+       terms of service.
+
+3. INTELLECTUAL PROPERTY
+   The Software is protected by copyright laws and international treaties.
+   maana retains all right, title, and interest in and to the Software,
+   including all intellectual property rights therein.
+
+4. TERMINATION
+   This license is effective until terminated. It will terminate automatically
+   if you fail to comply with any term of this license. Upon termination,
+   you must destroy all copies of the Software in your possession.
+
+5. DISCLAIMER OF WARRANTIES
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL MAANA BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+   DEALINGS IN THE SOFTWARE.
+
+7. GOVERNING LAW
+   This license shall be governed by and construed in accordance with the
+   laws of the Republic of Korea.
+
+For licensing inquiries, contact: support@issuesticker.com

package/README.md

@@ -0,0 +1,486 @@
+# IssueSticker SDK
+
+웹 애플리케이션에 시각적 버그 트래킹 위젯을 삽입하는 SDK입니다.
+사용자가 페이지 위에서 직접 클릭하여 이슈를 생성하고, 스크린샷/네트워크 로그/콘솔 로그를 자동으로 수집합니다.
+
+---
+
+## 목차
+
+- [주요 기능](#주요-기능)
+- [설치](#설치)
+- [빠른 시작](#빠른-시작)
+- [동작 모드](#동작-모드)
+- [API 레퍼런스](#api-레퍼런스)
+- [설정 옵션](#설정-옵션)
+- [이벤트](#이벤트)
+- [키보드 단축키](#키보드-단축키)
+- [위젯 기능](#위젯-기능)
+- [브라우저 지원](#브라우저-지원)
+- [FAQ](#faq)
+- [라이선스](#라이선스)
+
+---
+
+## 주요 기능
+
+- **클릭 기반 이슈 생성** — 페이지 위 원하는 위치를 클릭하여 마커 생성
+- **자동 스크린샷 캡처** — 이슈 생성 시점의 화면을 자동으로 캡처
+- **네트워크/콘솔 로그 수집** — 이슈 발생 전후의 네트워크 요청 및 콘솔 로그 자동 기록
+- **화면 녹화** — 버그 재현 과정을 영상으로 기록
+- **마커 표시** — 생성된 이슈를 페이지 위에 마커로 표시
+
+---
+
+## 설치
+
+### npm
+
+```bash
+npm install issue-sticker
+```
+
+### yarn
+
+```bash
+yarn add issue-sticker
+```
+
+### pnpm
+
+```bash
+pnpm add issue-sticker
+```
+
+### React 어댑터 사용 시 peer dependency
+
+`issue-sticker/react`를 사용할 경우 호스트 앱에 `react`, `react-dom`이 필요합니다.
+
+### CDN (script 태그)
+
+```html
+<script src="https://cdn.issuesticker.com/sdk/issue-sticker.umd.js"></script>
+<script>
+  IssueSticker.init({ apiKey: 'YOUR_API_KEY' });
+</script>
+```
+
+---
+
+## 빠른 시작
+
+### 엔트리포인트
+
+- `issue-sticker/runtime` — 프레임워크 비의존 코어 런타임 API (`IssueSticker`) (UI 마운트 없음)
+- `issue-sticker/react` — React 어댑터 API (`IssueSticker`, `useIssueSticker`) (위젯 UI 마운트 포함)
+
+화면 위젯(FAB/이슈 폼/마커)을 사용하려면 `issue-sticker/react` 경로를 사용해야 합니다.
+
+### React / Next.js
+
+`useIssueSticker` 훅을 사용하면 초기화와 정리를 자동으로 처리합니다.
+
+```tsx
+import { useIssueSticker } from 'issue-sticker/react';
+
+function App() {
+  useIssueSticker({ apiKey: 'YOUR_API_KEY' });
+
+  return <div>My Application</div>;
+}
+```
+
+### Vanilla JavaScript
+
+```typescript
+import { IssueSticker } from 'issue-sticker/runtime';
+
+IssueSticker.init({ apiKey: 'YOUR_API_KEY' });
+```
+
+`issue-sticker/runtime`은 코어 런타임 경로로, React UI 마운트 없이 SDK 엔진 라이프사이클/API 이벤트를 다룰 때 사용합니다.
+
+### HTML
+
+```html
+<script src="https://cdn.issuesticker.com/sdk/issue-sticker.umd.js"></script>
+<script>
+  IssueSticker.init({ apiKey: 'YOUR_API_KEY' });
+</script>
+```
+
+UMD(`issue-sticker.umd.js`)는 런타임 경로 기준입니다.
+UMD 경로는 위젯 UI를 자동 마운트하지 않습니다.
+
+---
+
+## 동작 모드
+
+SDK는 `user` 옵션 전달 여부에 따라 두 가지 모드로 동작합니다.
+아래 화면 동작(폼/마커/FAB)은 `issue-sticker/react` 경로로 위젯이 마운트된 상태를 기준으로 설명합니다.
+
+### 익명 모드 (기본)
+
+`user` 옵션 없이 초기화합니다. 이슈는 익명으로 생성되며, 사용자별 이슈 조회는 불가능합니다.
+
+```tsx
+useIssueSticker({ apiKey: 'YOUR_API_KEY' });
+```
+
+| 항목        | 동작               |
+| ----------- | ------------------ |
+| 이슈 생성   | 익명으로 생성      |
+| 이슈 조회   | 불가 (생성만 가능) |
+| 보고자 표시 | 표시 안 됨         |
+
+### 사용자 식별 모드
+
+호스트 앱의 사용자 정보를 `user`에 전달합니다. 이슈에 보고자 정보가 기록되고, 해당 사용자가 생성한 이슈만 조회할 수 있습니다.
+
+```tsx
+useIssueSticker({
+  apiKey: 'YOUR_API_KEY',
+  user: {
+    id: 'user-123',
+    name: 'Hong Gildong',
+  },
+});
+```
+
+| 항목        | 동작                             |
+| ----------- | -------------------------------- |
+| 이슈 생성   | 사용자 정보와 함께 생성          |
+| 이슈 조회   | 해당 사용자가 생성한 이슈만 표시 |
+| 보고자 표시 | `user.name`으로 표시             |
+
+### 멤버 모드
+
+워크스페이스에 등록된 멤버 계정으로 로그인합니다. FAB 메뉴의 "멤버 로그인"을 통해 진입할 수 있습니다.
+멤버 모드에서는 프로젝트의 모든 이슈를 조회/관리할 수 있으며, 마커를 페이지 위에 표시합니다.
+
+| 항목      | 동작                                      |
+| --------- | ----------------------------------------- |
+| 이슈 생성 | 멤버 계정으로 생성                        |
+| 이슈 조회 | 프로젝트의 모든 이슈 조회 가능            |
+| 마커      | 현재 페이지의 이슈를 마커로 표시          |
+| 이슈 관리 | 상태 변경, 심각도 변경, 댓글 등 전체 기능 |
+
+---
+
+## API 레퍼런스
+
+### `useIssueSticker(config)`
+
+React 커스텀 훅. 컴포넌트 마운트 시 SDK를 초기화하고, 언마운트 시 자동으로 정리합니다.
+
+```tsx
+import { useIssueSticker } from 'issue-sticker/react';
+
+function App() {
+  useIssueSticker({
+    apiKey: 'YOUR_API_KEY',
+    user: { id: 'user-123', name: 'Hong Gildong' },
+  });
+
+  return <div>My App</div>;
+}
+```
+
+`config.apiKey`, `config.user`, `config.enabled`가 변경되면 SDK를 자동으로 재초기화합니다.
+
+---
+
+### `IssueSticker.init(config)`
+
+SDK 코어 런타임을 초기화합니다.
+이 API(`issue-sticker/runtime`)는 위젯 UI를 자동 마운트하지 않습니다.
+React 환경에서는 `useIssueSticker` 훅 사용을 권장합니다.
+
+```typescript
+import { IssueSticker } from 'issue-sticker/runtime';
+```
+
+```typescript
+IssueSticker.init(config: SDKConfig): void
+```
+
+| 이름     | 타입        | 필수 | 설명          |
+| -------- | ----------- | ---- | ------------- |
+| `config` | `SDKConfig` | Yes  | SDK 설정 객체 |
+
+이미 초기화된 상태에서 다시 호출하면, 기존 런타임 상태를 정리한 뒤 새로 초기화합니다.
+
+---
+
+### `IssueSticker.destroy()`
+
+SDK 코어 런타임을 종료합니다.
+`issue-sticker/runtime` 경로에서는 위젯 언마운트를 수행하지 않습니다.
+
+```typescript
+IssueSticker.destroy(): void
+```
+
+---
+
+### `IssueSticker.on(event, callback)`
+
+SDK 이벤트를 구독합니다.
+
+```typescript
+IssueSticker.on(event: SDKEvent, callback: (...args: unknown[]) => void): void
+```
+
+**예시:**
+
+```typescript
+IssueSticker.on('issue:created', (issue) => {
+  console.log('새 이슈:', issue);
+});
+
+IssueSticker.on('error', (error) => {
+  console.error('SDK 오류:', error);
+});
+```
+
+---
+
+### `IssueSticker.off(event, callback)`
+
+등록된 이벤트 구독을 해제합니다.
+
+```typescript
+IssueSticker.off(event: SDKEvent, callback: (...args: unknown[]) => void): void
+```
+
+**예시:**
+
+```typescript
+const handler = (issue) => console.log(issue);
+IssueSticker.on('issue:created', handler);
+
+// 나중에 구독 해제
+IssueSticker.off('issue:created', handler);
+```
+
+---
+
+## 설정 옵션
+
+### `SDKConfig`
+
+| 속성      | 타입      | 필수 | 설명                                                           |
+| --------- | --------- | ---- | -------------------------------------------------------------- |
+| `apiKey`  | `string`  | Yes  | IssueSticker API 키. [대시보드](https://app.issuesticker.com)에서 발급 |
+| `user`    | `SDKUser` | No   | 호스트 앱의 사용자 정보. 전달 시 사용자 식별 모드로 동작       |
+| `enabled` | `boolean` | No   | SDK 활성화 여부 (기본값: `true`). `useIssueSticker` 훅 전용        |
+
+### `SDKUser`
+
+| 속성   | 타입     | 필수 | 설명               |
+| ------ | -------- | ---- | ------------------ |
+| `id`   | `string` | Yes  | 사용자 고유 식별자 |
+| `name` | `string` | Yes  | 사용자 표시 이름   |
+
+---
+
+## 이벤트
+
+SDK는 다양한 이벤트를 발생시켜 위젯의 상태 변화를 알려줍니다.
+
+| 이벤트              | 발생 시점           | 콜백 인자           |
+| ------------------- | ------------------- | ------------------- |
+| `ready`             | SDK 초기화 완료     | —                   |
+| `error`             | 오류 발생           | `error: string`     |
+| `issue:created`     | 이슈 생성 완료      | `issue: object`     |
+| `issue:updated`     | 이슈 수정 완료      | `issue: object`     |
+| `issue:clicked`     | 마커 클릭           | `issueId: string`   |
+| `mode:changed`      | 이슈 생성 모드 변경 | `isActive: boolean` |
+| `recording:started` | 화면 녹화 시작      | —                   |
+| `recording:stopped` | 화면 녹화 종료      | —                   |
+| `auth:login`        | 멤버 로그인 성공    | —                   |
+| `auth:logout`       | 로그아웃 완료       | —                   |
+
+---
+
+## 키보드 단축키
+
+| 단축키               | 기능                |
+| -------------------- | ------------------- |
+| `Ctrl/Cmd + Alt + 1` | 이슈 생성 모드 토글 |
+| `Ctrl/Cmd + Alt + 2` | 화면 녹화 시작/중지 |
+| `Esc`                | 이슈 생성 모드 종료 |
+
+---
+
+## 위젯 기능
+
+### FAB (Floating Action Button)
+
+`issue-sticker/react` 경로로 SDK를 초기화하면 우측 하단에 플로팅 버튼이 나타납니다.
+
+| 메뉴             | 설명                     | 조건           |
+| ---------------- | ------------------------ | -------------- |
+| 이슈 생성        | 이슈 생성 모드 진입/종료 | 항상 표시      |
+| 화면 녹화        | 화면 녹화 시작/중지      | 항상 표시      |
+| 마커 보기/숨기기 | 마커 표시 토글           | 멤버 로그인 시 |
+| 멤버 로그인      | 워크스페이스 멤버 로그인 | 비로그인 시    |
+| 로그아웃         | 멤버 로그아웃            | 로그인 시      |
+
+### 이슈 생성 모드
+
+이슈 생성은 **스크린샷 모드**와 **영상 녹화 모드** 두 가지 방식을 지원합니다.
+
+#### 스크린샷 모드
+
+이슈 생성 시점의 화면을 정지 이미지로 캡처합니다.
+
+1. FAB 메뉴에서 "이슈 생성" 클릭 또는 `Ctrl/Cmd + Alt + 1`
+2. 커서가 십자 모양으로 변경되고, 마우스 오버 시 요소가 하이라이트됨
+3. 원하는 위치 클릭 → 이슈 생성 폼 표시 (스크린샷 자동 첨부)
+4. 폼 작성 후 제출
+
+#### 영상 녹화 모드
+
+버그 재현 과정을 영상으로 기록한 후 이슈에 첨부합니다.
+
+1. FAB 메뉴에서 "화면 녹화" 클릭 또는 `Ctrl/Cmd + Alt + 2`
+2. 화면 녹화가 시작됨 (녹화 인디케이터 표시)
+3. 버그를 재현한 후, FAB 메뉴에서 "녹화 중지" 클릭 또는 `Ctrl/Cmd + Alt + 2`
+4. 녹화 종료 후 자동으로 이슈 생성 모드 진입
+5. 원하는 위치 클릭 → 이슈 생성 폼 표시 (녹화 영상 자동 첨부)
+6. 폼 작성 후 제출
+
+> **참고**: SDK의 영상 녹화는 브라우저 `getDisplayMedia` API를 사용합니다. 녹화 중 페이지를 리로드하거나 다른 페이지로 이동하면 녹화가 중단되며 녹화 데이터가 유실됩니다. 페이지 이동에도 끊김 없는 녹화가 필요한 경우, [IssueSticker Chrome Extension](https://chrome.google.com/webstore)을 설치하면 백그라운드 녹화를 지원하여 페이지 리로드에도 녹화가 유지됩니다.
+
+### 자동 수집 데이터
+
+| 데이터        | 설명                                           |
+| ------------- | ---------------------------------------------- |
+| 스크린샷      | 클릭 시점의 페이지 스크린샷                    |
+| 영상          | 화면 녹화 영상 (녹화 모드 사용 시)             |
+| 네트워크 로그 | 최근 50개 네트워크 요청 (URL, 상태, 소요 시간) |
+| 콘솔 로그     | 최근 50개 콘솔 출력 (log, warn, error)         |
+| User Agent    | 브라우저 및 OS 정보                            |
+| 클릭 위치     | 클릭한 요소의 CSS 선택자 및 XPath              |
+
+> **참고**: 출시 이후 SDK 위젯 내부에 1회성 제품 안내가 추가될 수 있습니다. 이 안내는 `SDKConfig` 옵션이나 public API로 제어하지 않고, IssueSticker Shadow DOM 내부 UI만 대상으로 하며 localStorage로 기본 1회 노출 여부를 관리합니다.
+
+---
+
+## 브라우저 지원
+
+| 브라우저 | 최소 버전 |
+| -------- | --------- |
+| Chrome   | 90+       |
+| Firefox  | 90+       |
+| Safari   | 15+       |
+| Edge     | 90+       |
+
+---
+
+## FAQ
+
+### API 키는 어디서 발급받나요?
+
+[IssueSticker 대시보드](https://app.issuesticker.com)에서 프로젝트를 생성한 후 SDK 설정 페이지에서 API 키를 발급받을 수 있습니다.
+
+### 호스트 페이지의 CSS에 영향을 주나요?
+
+`issue-sticker/react` 경로를 사용하는 경우, SDK 위젯은 호스트 페이지의 스타일과 격리되어 동작합니다. 단, 이슈 생성 모드에서 커서 변경과 요소 하이라이트를 위한 최소한의 스타일이 추가됩니다.
+
+### SPA(Single Page Application)에서 사용할 수 있나요?
+
+네. URL 변경을 자동으로 감지하여 새 페이지의 이슈를 로드합니다. 위젯 UI까지 사용하려면 `useIssueSticker`를 `issue-sticker/react`에서 import해 앱 최상위에서 사용하는 방식을 권장합니다.
+
+### `Invalid hook call` / `Cannot read properties of null (reading 'useRef')` 오류가 나요
+
+이 오류는 대부분 **호스트 앱에 React 인스턴스가 2개 이상 로드**될 때 발생합니다.
+
+1. 의존성 중복 확인
+
+```bash
+npm ls react react-dom
+```
+
+`react`, `react-dom`이 단일 버전으로 정리되어 있는지 확인하세요.
+
+2. Vite 사용 시 dedupe 설정
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  resolve: {
+    dedupe: ['react', 'react-dom'],
+  },
+});
+```
+
+Webpack/Next.js 사용 시에는 alias로 React 경로를 단일화하세요.
+
+```js
+// next.config.js 또는 webpack config
+const path = require('path');
+
+module.exports = {
+  webpack: (config) => {
+    config.resolve.alias = {
+      ...(config.resolve.alias || {}),
+      react: path.resolve(__dirname, 'node_modules/react'),
+      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
+    };
+    return config;
+  },
+};
+```
+
+3. import 경로 점검
+
+- React 환경: `import { useIssueSticker } from 'issue-sticker/react'`
+- 비 React 환경: `import { IssueSticker } from 'issue-sticker/runtime'`
+
+루트(`issue-sticker`)에서 React 훅을 import하지 않도록 주의하세요.
+`issue-sticker/react`를 사용할 때는 호스트 앱에 `react`, `react-dom`이 반드시 설치되어 있어야 합니다.
+
+`[plugin:vite:import-analysis] Missing "./react" specifier in "issue-sticker" package` 오류가 보이면,
+설치된 SDK tarball/lockfile이 오래된 상태일 가능성이 큽니다. `node_modules`와 lockfile을 갱신한 뒤 SDK를 재설치하세요.
+
+### 리액트 없이도 사용할 수 있나요?
+
+네. `issue-sticker/runtime`으로 코어 런타임 초기화/이벤트 연동은 가능합니다.
+다만 FAB/이슈 폼/마커 같은 위젯 UI 기능은 `issue-sticker/react` 경로(React 환경)에서만 동작합니다.
+
+### user 정보를 넣으면 어떤 효과가 있나요?
+
+[동작 모드](#동작-모드) 섹션을 참조하세요. `user.id`를 전달하면 사용자 식별 모드로 동작하여 해당 사용자가 생성한 이슈만 조회할 수 있고, `user.name`이 보고자로 기록됩니다.
+
+### 이슈 데이터는 어디에 저장되나요?
+
+IssueSticker 클라우드 서버에 안전하게 저장됩니다. API 키에 연결된 프로젝트에 이슈가 귀속됩니다.
+
+### 프로덕션 환경에서도 사용해도 되나요?
+
+네. 다만 일반 사용자에게 노출하지 않으려면 특정 조건(예: 관리자 모드, 스테이징 환경)에서만 SDK를 초기화하도록 분기 처리하는 것을 권장합니다.
+
+```tsx
+import { useIssueSticker } from 'issue-sticker/react';
+
+function App() {
+  useIssueSticker({
+    apiKey: 'YOUR_API_KEY',
+    enabled: isAdminMode || isStagingEnv,
+  });
+
+  return <div>My App</div>;
+}
+```
+
+---
+
+## 라이선스
+
+Copyright (c) 2026 maana. All rights reserved.
+
+이 소프트웨어는 maana의 독점 소유물입니다. 자세한 내용은 [LICENSE](./LICENSE) 파일을 참조하세요.