npm - issue-sticker - Versions diffs - 0.2.2 → 0.3.1 - Mend

issue-sticker 0.2.2 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/CHANGELOG.md +31 -0
package/README.md +100 -137
package/dist/{createLucideIcon-B457EluY.js → createLucideIcon-CmSNiW63.js} +19 -17
package/dist/{externalUserPayload-C2hxbvaU.js → externalUserPayload-hJjuUx6q.js} +154 -57
package/dist/issue-sticker-headless-react.js +2 -2
package/dist/issue-sticker-headless.js +15 -9
package/dist/issue-sticker-react.js +580 -130
package/dist/{tooltip-BkQcdrki.js → tooltip-DciWyUWs.js} +1 -1
package/headless.d.ts +139 -10
package/package.json +5 -4

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,37 @@
 npm 패키지 `issue-sticker`의 변경 이력입니다. 설치·업그레이드에 영향을 주는 변경만 기록합니다.
+## 0.3.1 - 2026-08-17
+### 수정
+- `issue-sticker/headless`의 타입 선언이 패키지에 함께 배포되지 않는 내부 모듈을 참조해, 이 경로를 타입과 함께 사용하는 프로젝트에서 타입 검사가 실패하던 문제를 수정했습니다. 공개 타입은 이제 패키지 안에서 자체 선언하며, 내부 식별자 컬럼은 공개 타입에 포함하지 않습니다.
+### 주의가 필요한 변경
+- `issue-sticker/react.js`, `issue-sticker/headless.js`, `issue-sticker/headless/react.js` 경로를 제거했습니다. 문서에 없던 중복 경로이며 타입 정의도 연결되어 있지 않았습니다. 공개 경로는 `issue-sticker/react`, `issue-sticker/headless`, `issue-sticker/headless/react` 세 개입니다.
+## 0.3.0 - 2026-08-12
+### 추가
+- 이슈 생성 폼과 이슈 상세에서 프로젝트 커스텀 필드를 입력·조회할 수 있습니다. 커스텀 필드는 Jira 연동 여부와 무관하게 표시됩니다.
+- `select`, `multi_select`, `boolean` 등 커스텀 필드 타입별 입력과 표시를 지원하고, 옵션형 필드는 태그 기반 UI로 다룹니다.
+- Headless SDK의 익명 이슈 상세 조회 요청에 게스트 소유자 식별자를 함께 전송합니다.
+### 개선
+- Jira 계정 연결 안내를 이슈 폼과 대시보드 흐름 안에서 확인할 수 있게 정리했습니다.
+- 이슈 폼 입력 중 호스트 페이지 단축키가 함께 실행되지 않도록 이벤트 처리를 보강했습니다.
+- SDK 런타임 호스트를 최상위 레이어로 올려, 호스트 앱 UI에 이슈 생성 팝업이 가려지는 상황을 줄였습니다.
+- 토스트 배경과 상태 아이콘 색상을 공용 토큰 기준으로 맞춰 알림 가독성을 개선했습니다.
+### 수정
+- 소유자 식별자가 없는 익명 이슈에서 편집·삭제 진입점이 노출되던 문제를 수정했습니다.
+- Jira 연결 직후 필드가 조회 불가로 보이거나 연결 실패 안내가 누락되던 문제를 수정했습니다.
+- Notion 필드 저장 실패와 외부 연동 피드백을 toast로 일관되게 표시합니다.
 ## 0.2.2 - 2026-08-06
 ### 수정

package/README.md CHANGED Viewed

@@ -1,122 +1,105 @@
-## 개요
+# issue-sticker
+이 문서는 이슈스티커 SDK(IssueSticker SDK for JavaScript) 사용 방법을 안내합니다.
-이 README는 `issue-sticker` SDK의 설치 방법과 공개 API 표면만 다룹니다.
+사용자가 화면을 클릭해 이슈를 남기면 스크린샷과 콘솔·네트워크 로그, 브라우저 정보가 함께 기록됩니다.
+## 준비
-프로젝트 생성, 허용 도메인 등록, API key 발급, 제품별 운영 방식은 아래 가이드에서 확인하세요.
+### 지원 환경
+`issue-sticker/react`와 `issue-sticker/headless/react`는 React 어댑터입니다. 앱에 `react`, `react-dom` 18 또는 19가 설치되어 있어야 합니다.
-| 가이드                                                           | 내용                                          |
-| ---------------------------------------------------------------- | --------------------------------------------- |
-| [시작 준비](https://issuesticker.com/guide/products/setup)       | 프로젝트 생성, 허용 도메인 등록, API key 발급 |
-| [SDK Widget](https://issuesticker.com/guide/products/sdk)        | 위젯 설치, 초기화, 운영 환경에서 켜는 조건    |
-| [SDK Headless](https://issuesticker.com/guide/products/headless) | Headless 클라이언트 전체 레퍼런스             |
-| [외부 연동](https://issuesticker.com/guide/integrations)         | Jira·Notion 연결과 필드 동기화                |
-| [FAQ](https://issuesticker.com/guide/faq)                        | 권한, 도메인, key, 필드 동기화 문제 해결      |
+`issue-sticker/headless`는 React를 요구하지 않습니다. 프레임워크에 상관없이 사용할 수 있습니다.
+### API key 발급
+[관리자 콘솔](https://app.issuesticker.com)에서 프로젝트를 만들고, 위젯을 노출할 도메인을 허용 도메인으로 등록한 뒤 SDK API key를 발급받아야 합니다. SDK는 API key와 등록된 도메인을 기준으로 초기화합니다. 둘 중 하나라도 빠지면 위젯이 나타나지 않습니다.
+발급 절차는 [시작 준비](https://issuesticker.com/guide/products/setup)에 있습니다.
 ## 설치
+앱에 `issue-sticker` 패키지를 설치합니다.
 ```bash
 npm install issue-sticker
 ```
-`issue-sticker/react`와 `issue-sticker/headless/react`를 사용하려면 연동하는 앱에 `react`, `react-dom` 18 또는 19가 설치되어 있어야 합니다.
-## 엔트리포인트
-| 경로                           | 용도                                                  |
-| ------------------------------ | ----------------------------------------------------- |
-| `issue-sticker/react`          | 위젯 UI(FAB, 이슈 폼, 마커)를 마운트하는 React 어댑터 |
-| `issue-sticker/headless`       | UI 없이 이슈 흐름을 구독하고 제어하는 컨트롤러 API    |
-| `issue-sticker/headless/react` | Headless UI를 직접 만들 때 사용하는 최소 React 헬퍼   |
+| 경로                           | 용도                                                    |
+| ------------------------------ | ------------------------------------------------------- |
+| `issue-sticker/react`          | 위젯 UI(FAB, 이슈 폼, 마커)를 마운트하는 React 어댑터   |
+| `issue-sticker/headless`       | UI 없이 이슈 흐름을 구독하고 제어하는 컨트롤러 API      |
+| `issue-sticker/headless/react` | Headless UI를 직접 만들 때 사용하는 최소 React 헬퍼     |
+## 초기화
-패키지 루트(`issue-sticker`)와 `issue-sticker/runtime`은 공개 엔트리포인트가 아닙니다.
-## 빠른 시작 — 위젯
+이슈스티커 초기화를 위한 컴포넌트를 생성합니다.
 ```tsx
 'use client'; // Next.js App Router
 import { useIssueSticker } from 'issue-sticker/react';
-function App() {
+export function IssueStickerWidget() {
+  const { user } = useAuth(); // 앱의 사용자 정보
   useIssueSticker({
     apiKey: process.env.NEXT_PUBLIC_ISSUE_STICKER_SDK_KEY!,
-    user: { id: 'user-123', name: 'Hong Gildong' }, // 선택: 작성자 식별
-    enabled: isStaging || isAdmin, // 선택: 노출 조건 (기본 true)
+    user: user ? { id: user.id, name: user.name } : undefined, // 사용자 식별
+    enabled: isStaging || user?.role === 'admin', // 노출 조건
   });
-  return <div>My Application</div>;
+  return null;
 }
 ```
+### 사용자 식별
-앱 최상위에서 한 번만 호출하세요.
-훅은 마운트 시 SDK를 초기화하고, 언마운트 시 정리합니다.
-오른쪽 아래에 표시되는 FAB는 드래그로 위치를 옮길 수 있습니다.
-FAB에서는 이슈 생성, 화면 녹화, 마커 표시 토글, 마커 기준 전환(생성 위치 기준 / 대상 요소 기준), 미표시 스티커 확인, 가이드 다시 보기, 멤버 로그인·로그아웃을 사용할 수 있습니다.
+| 모드        | 설정                | 이슈 조회 범위                                    | 수정·삭제                 |
+| ----------- | ------------------- | ------------------------------------------------- | ------------------------- |
+| 익명        | `user` 없이 초기화  | 조회 없음 (이번 세션에서 만든 이슈만 화면에 표시) | 불가 (자기가 만든 이슈도) |
+| 사용자 식별 | `user` 전달         | 해당 사용자가 만든 이슈                           | 자기가 만든 이슈만        |
+| 멤버        | FAB의 "멤버 로그인" | 프로젝트의 모든 이슈                              | 프로젝트의 모든 이슈      |
+### 위젯 기능
-이슈 생성 모드와 화면 녹화는 동시에 켤 수 없습니다.
+초기화를 마치면 화면 오른쪽 아래에 FAB가 표시됩니다. FAB는 아래 기능을 제공하며, 드래그로 위치를 옮길 수 있습니다.
+- 이슈 생성
+- 화면 녹화
+- 마커 표시 토글
+- 마커 기준 전환(생성 위치 기준 / 대상 요소 기준)
+- 미표시 스티커 확인
+- 가이드 다시 보기
+- 멤버 로그인·로그아웃
-## 빠른 시작 — Headless
+### 단축키
-```typescript
-import { createIssueStickerHeadless } from 'issue-sticker/headless';
-const client = createIssueStickerHeadless({
-  apiKey: 'YOUR_API_KEY',
-  user: { id: 'user-123', name: 'Hong Gildong' },
-});
-client.subscribe((snapshot) => renderIssueUI(snapshot));
-await client.initialize();
-await client.refreshIssues();
-```
-현재 상태는 읽기 전용 snapshot으로 제공되며, 이슈 생성은 `startIssueCapture()`로 시작합니다.
-전체 메서드, snapshot 타입, 동적 필드 descriptor, 에러 코드는 [Headless 가이드](https://issuesticker.com/guide/products/headless)를 참고하세요.
-## API — `issue-sticker/react`
-### `useIssueSticker(config)`
-React 훅입니다.
-`apiKey` 또는 `enabled`가 바뀌면 위젯을 다시 초기화하고, `user`가 바뀌면 위젯은 유지한 채 설정만 갱신합니다.
+| 기능                | macOS       | Windows·Linux |
+| ------------------- | ----------- | ------------- |
+| 이슈 생성 모드 토글 | `⌘⌥1` `⌃⌥1` | `Ctrl+Alt+1`  |
+| 화면 녹화 시작/중지 | `⌘⌥2` `⌃⌥2` | `Ctrl+Alt+2`  |
+| 이슈 생성 모드 종료 | `Esc`       | `Esc`         |
-### `IssueSticker`
+### 설정
-훅을 사용할 수 없는 환경에서 직접 제어할 때 사용합니다.
+| 속성                    | 타입                                 | 필수 | 설명                                                                                        |
+| ----------------------- | ------------------------------------ | ---- | ------------------------------------------------------------------------------------------- |
+| `apiKey`                | `string`                             | O    | 관리자 콘솔에서 발급한 SDK API key                                                          |
+| `user`                  | `SDKUser`                            | X    | 앱의 사용자 정보. 제공하면 작성자가 기록되고 자기 이슈를 조회·수정·삭제할 수 있습니다 |
+| `onboarding`            | `'off' \| 'onMount' \| 'onFABClick'` | X    | 온보딩 가이드 트리거. 기본값 `'onMount'`. `'off'`면 "가이드 다시 보기" 버튼도 숨겨집니다           |
+| `screenshotCompression` | `{ useWebWorker?: boolean }`         | X    | 스크린샷 압축을 Web Worker에서 할지 여부                                                    |
+| `enabled`               | `boolean`                            | X    | 위젯 활성화 여부. 기본값 `true`. `useIssueSticker` 전용                                     |
+컴포넌트가 마운트되면 위젯을 초기화하고, 언마운트되면 정리합니다. `apiKey`나 `enabled`가 바뀌면 위젯을 다시 초기화하고, `user`만 바뀌면 위젯을 유지한 채 설정만 갱신합니다.
-| 메서드                            | 설명                                                                                                  |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `init(config: SDKConfig)`         | SDK를 초기화하고 위젯을 마운트합니다. 이미 초기화된 상태라면 설정을 갱신하고 위젯을 다시 마운트합니다 |
-| `updateConfig(config: SDKConfig)` | 위젯을 유지한 채 설정만 교체합니다. 초기화 전이면 `init`과 동일하게 동작합니다                        |
-| `destroy()`                       | 위젯을 언마운트하고 SDK를 종료합니다                                                                  |
+### 훅 없이 초기화하기
+React 훅을 사용할 수 없는 경우 `IssueSticker`로 직접 제어합니다.
 ```typescript
 import { IssueSticker } from 'issue-sticker/react';
@@ -124,92 +107,72 @@ import { IssueSticker } from 'issue-sticker/react';
 IssueSticker.init({ apiKey: 'YOUR_API_KEY' });
 ```
+#### init(config)
-이슈 생성·제출 흐름을 연동하는 앱에서 직접 구독하거나 제어해야 한다면 Headless 클라이언트를 사용하세요.
-상태는 `subscribe()`로 구독하고, 캡처와 제출은 메서드로 제어할 수 있습니다.
-자세한 내용은 [Headless 가이드](https://issuesticker.com/guide/products/headless)를 참고하세요.
-### `SDKConfig`
-| 속성                    | 타입                                 | 필수 | 설명                                                                                        |
-| ----------------------- | ------------------------------------ | ---- | ------------------------------------------------------------------------------------------- |
-| `apiKey`                | `string`                             | Yes  | [관리자 콘솔](https://app.issuesticker.com)에서 발급한 SDK API key                          |
-| `user`                  | `SDKUser`                            | No   | 연동하는 앱의 사용자 정보. 전달하면 작성자가 기록되고 자신이 만든 이슈를 조회할 수 있습니다 |
-| `onboarding`            | `'off' \| 'onMount' \| 'onFABClick'` | No   | 온보딩 가이드 트리거 (기본 `'onMount'`). `'off'`면 "가이드 다시 보기"도 숨깁니다            |
-| `screenshotCompression` | `{ useWebWorker?: boolean }`         | No   | 스크린샷 압축을 Web Worker에서 수행할지 여부                                                |
-| `enabled`               | `boolean`                            | No   | 위젯 활성화 여부 (기본 `true`). `useIssueSticker` 전용 옵션                                 |
-`SDKUser`는 `id`, `name` 두 필드가 모두 필요합니다.
-### 키보드 단축키
+```typescript
+init(config: SDKConfig): void
+```
+SDK를 초기화하고 위젯을 마운트합니다. 이미 초기화된 상태에서 다시 호출하면 설정을 갱신하고 위젯을 다시 마운트합니다.
-| 기능                | macOS       | Windows·Linux |
-| ------------------- | ----------- | ------------- |
-| 이슈 생성 모드 토글 | `⌘⌥1` `⌃⌥1` | `Ctrl+Alt+1`  |
-| 화면 녹화 시작/중지 | `⌘⌥2` `⌃⌥2` | `Ctrl+Alt+2`  |
-| 이슈 생성 모드 종료 | `Esc`       | `Esc`         |
+#### updateConfig(config)
-## 이슈에 담기는 정보
+```typescript
+updateConfig(config: SDKConfig): void
+```
+위젯을 유지한 채 설정만 교체합니다. 초기화 전에 호출하면 `init`과 같게 동작합니다.
-- 스크린샷 — 화면 전체와 클릭한 요소 영역 (클릭 직후 백그라운드에서 캡처)
-- 화면 녹화 영상 — 녹화 모드로 생성한 경우
-- 네트워크·콘솔 로그 — 각각 최근 50개, IssueSticker 자체 트래픽은 제외
-- 브라우저·OS 정보, 발생 URL, 클릭한 요소의 CSS 선택자와 XPath
-- 세션 리플레이 — 워크스페이스에서 사용할 수 있는 경우, 이슈 폼에서 첨부 여부 선택
+#### destroy()
+```typescript
+destroy(): void
+```
-화면의 마커를 클릭하면 이슈 팝오버에서 제목과 설명을 수정하고, 이슈를 삭제하고, 코딩 에이전트에 붙여 넣을 LLM 프롬프트를 복사할 수 있습니다.
-연동된 Jira·Notion 정보는 멤버로 로그인했을 때 함께 표시됩니다.
+위젯을 언마운트하고 SDK를 종료합니다.
+## Headless 클라이언트
-화면 녹화는 브라우저 `getDisplayMedia` API를 사용합니다.
-녹화 중 페이지를 새로고침하거나 다른 페이지로 이동하면 녹화가 중단되고 데이터가 유실됩니다.
+이슈 리포팅 버튼과 폼을 제품 디자인에 맞춰 직접 만들 때 사용합니다. 클라이언트를 만들고, 상태를 구독하고, 초기화하면 준비가 끝납니다.
+```typescript
+import { createIssueStickerHeadless } from 'issue-sticker/headless';
-페이지 이동 중에도 끊기지 않는 녹화가 필요하면 [Chrome Extension](https://issuesticker.com/guide/products/extension)을 사용하세요.
+const client = createIssueStickerHeadless({
+  apiKey: 'YOUR_API_KEY',
+  user: { id: currentUser.id, name: currentUser.name },
+});
+const unsubscribe = client.subscribe((snapshot) => renderYourUI(snapshot));
-## 사용자 식별
+await client.initialize();
+await client.refreshIssues();
+captureButton.onclick = () => client.startIssueCapture();
+```
-| 모드        | 설정                | 이슈 조회 범위                                        |
-| ----------- | ------------------- | ----------------------------------------------------- |
-| 익명        | `user` 없이 초기화  | 조회 없음 (이번 세션에서 생성한 이슈만 화면에 표시됨) |
-| 사용자 식별 | `user` 전달         | 해당 사용자가 생성한 이슈                             |
-| 멤버        | FAB의 "멤버 로그인" | 프로젝트의 모든 이슈                                  |
+클라이언트는 현재 상태를 읽기 전용 snapshot으로 넘겨줍니다. 메서드 전체, phase와 snapshot 모델, 동적 필드 descriptor, 에러 코드는 [Headless 가이드](https://issuesticker.com/guide/products/headless)에 있습니다.
 ## 문제 해결
+- 위젯이 보이지 않으면 프로젝트에 등록한 허용 도메인과 현재 `window.location.origin`이 같은지 확인하세요.
+- 특정 사용자에게만 노출했다면 `enabled` 조건이 실제 로그인 상태와 맞는지 확인하세요.
+- `Invalid hook call` 또는 `Cannot read properties of null (reading 'useRef')`는 대부분 React가 두 벌 로드된 경우입니다. `npm ls react react-dom`으로 확인하고, Vite는 `resolve.dedupe: ['react', 'react-dom']`을, Webpack·Next.js는 alias로 React 경로를 하나로 맞추세요.
+- `Missing "./react" specifier in "issue-sticker" package`는 설치된 패키지가 오래된 경우입니다. `node_modules`와 lockfile을 지우고 다시 설치하세요.
-`Invalid hook call` 또는 `Cannot read properties of null (reading 'useRef')` 오류는 대부분 React 인스턴스가 중복으로 로드될 때 발생합니다.
-`npm ls react react-dom`으로 중복 설치 여부를 확인하세요.
-Vite는 `resolve.dedupe: ['react', 'react-dom']`을 설정하고, Webpack·Next.js는 alias로 React 경로를 하나로 맞추면 됩니다.
-`Missing "./react" specifier in "issue-sticker" package` 오류는 설치된 패키지가 오래된 경우에 발생합니다.
-`node_modules`와 lockfile을 갱신한 뒤 다시 설치하세요.
-그 밖의 문제는 [FAQ](https://issuesticker.com/guide/faq)를 참고하세요.
+## 더 보기
+| 가이드                                                           | 내용                                          |
+| ---------------------------------------------------------------- | --------------------------------------------- |
+| [시작 준비](https://issuesticker.com/guide/products/setup)       | 프로젝트 생성, 허용 도메인 등록, API key 발급 |
+| [SDK Widget](https://issuesticker.com/guide/products/sdk)        | 위젯 설치, 초기화, 운영 환경에서 켜는 조건    |
+| [SDK Headless](https://issuesticker.com/guide/products/headless) | 메서드, phase와 snapshot, 에러 코드 레퍼런스  |
+| [외부 연동](https://issuesticker.com/guide/integrations)         | Jira·Notion 연결과 필드 동기화                |
+| [FAQ](https://issuesticker.com/guide/faq)                        | 권한, 도메인, key, 필드 동기화 문제 해결      |
 ## 라이선스
 Copyright (c) 2026 maana. All rights reserved.
-이 소프트웨어는 maana의 독점 소유물입니다.
-자세한 내용은 [LICENSE](./LICENSE) 파일을 참조하세요.
+이 소프트웨어는 maana의 독점 소유물입니다. 자세한 내용은 [LICENSE](./LICENSE)를 참조하세요.

package/dist/{createLucideIcon-B457EluY.js → createLucideIcon-CmSNiW63.js} RENAMED Viewed

@@ -21612,6 +21612,23 @@ class Replayer {
     this.config.logger.log(REPLAY_CONSOLE_PREFIX, ...args);
   }
 }
+const OVERLAY_LAYER_INDEX = {
+  // 익스텐션·SDK 위젯의 shadow host. isolation:isolate 로 stacking context 를 만들기 때문에
+  // 아래 레이어 값들은 호스트 내부 순서만 정한다. 호스트 페이지의 오버레이와 겨루는 것은
+  // 이 값 하나뿐이라, 페이지가 쓸 수 있는 어떤 레이어보다 위여야 한다.
+  runtimeHost: 2147483647,
+  fab: 999999,
+  tourMask: 1000006,
+  tourPopover: 1000007
+};
+const OVERLAY_LAYER = {
+  shell: "z-[1000000]",
+  sdkLoginOverlay: "z-[1000003]",
+  dialogOverlay: "z-[1000004]",
+  dialogContent: "z-[1000005]",
+  floating: "z-[1000008]",
+  toast: "z-[1000010]"
+};
 function r(e2) {
   var t2, f2, n2 = "";
   if ("string" == typeof e2 || "number" == typeof e2) n2 += e2;
@@ -27246,21 +27263,6 @@ function stopEscapePropagation(handler) {
     event.stopPropagation();
   };
 }
-const OVERLAY_LAYER_INDEX = {
-  sdkHost: 999999,
-  fab: 999999,
-  tourMask: 1000006,
-  tourPopover: 1000007,
-  sdkLoginHost: 2147483647
-};
-const OVERLAY_LAYER = {
-  shell: "z-[1000000]",
-  sdkLoginOverlay: "z-[1000003]",
-  dialogOverlay: "z-[1000004]",
-  dialogContent: "z-[1000005]",
-  floating: "z-[1000008]",
-  toast: "z-[1000010]"
-};
 const PortalContainerContext = React.createContext(void 0);
 function PortalContainerProvider({ container: container2, children }) {
   return /* @__PURE__ */ jsx(PortalContainerContext.Provider, { value: container2, children });
@@ -27381,7 +27383,7 @@ export {
   Anchor as A,
   Content as C,
   DismissableLayer as D,
-  OVERLAY_LAYER as O,
+  OVERLAY_LAYER_INDEX as O,
   Primitive as P,
   Replayer as R,
   Slot as S,
@@ -27389,7 +27391,7 @@ export {
   cn as a,
   usePortalContainer as b,
   createLucideIcon as c,
-  OVERLAY_LAYER_INDEX as d,
+  OVERLAY_LAYER as d,
   useControllableState as e,
   useId as f,
   composeEventHandlers as g,