issue-sticker 0.11.0 → 0.13.0

package/headless.d.ts

@@ -101,6 +101,27 @@ export interface IssueStickerSummary {
     readonly color: string;
     readonly label: string | null;
   } | null;
+  /** 영상 URL. 업로드 중이거나 영상이 없으면 `null` 입니다. */
+  video?: string | null;
+  /**
+   * 영상 업로드 상태. `submitDraft()` 직후에는 `'uploading'` 이고, 업로드가 끝나면
+   * `snapshot.issues` 의 같은 이슈가 `'ready'` 로 바뀝니다. 영상 URL 은 `openIssue()` 로 연
+   * `snapshot.activeIssue.video` 에서 확인합니다. 업로드를 끝내 포기하면 `'failed'` 입니다.
+   * 영상이 없으면 `null`.
+   */
+  video_status?: 'uploading' | 'ready' | 'failed' | null;
+  /**
+   * 영상 업로드를 끝내 포기한 이유. `video_status` 가 `'failed'` 이고 이유를 알 때만 있습니다.
+   * 업로드하는 동안 프로젝트 마스킹 정책이 화면 녹화를 막으면 `'masking_video_excluded'` 이고,
+   * 이슈는 영상 없이 남습니다.
+   */
+  video_failure_reason?: 'masking_video_excluded' | null;
+  /**
+   * 세션 리플레이 업로드 상태. 리플레이가 있는 이슈는 `submitDraft()`·`createIssue()` 직후
+   * `'uploading'` 이고, 업로드가 끝나면 `snapshot.issues` 의 같은 이슈가 `'ready'` 로 바뀝니다.
+   * 업로드를 끝내 포기하면 `'failed'` 이고 그 이슈에는 리플레이가 없습니다. 리플레이가 없으면 `null`.
+   */
+  replay_status?: 'uploading' | 'ready' | 'failed' | null;
 }
 
 /** 상세 조회한 이슈. */
@@ -162,7 +183,15 @@ export type HeadlessErrorCode =
   | 'NETWORK_ERROR'
   | 'CAPTURE_FAILED'
   | 'VALIDATION_ERROR'
-  | 'PAYLOAD_TOO_LARGE';
+  | 'PAYLOAD_TOO_LARGE'
+  /** 워크스페이스 마스킹 정책을 불러오지 못해 이슈를 만들지 않았다. 네트워크를 확인한 뒤 다시 제출한다. */
+  | 'MASKING_POLICY_UNAVAILABLE'
+  /** 제출 중 프로젝트의 화면 마스킹 규칙이 바뀌었다. 스크린샷·세션 리플레이를 새로 만든 뒤 제출한다. */
+  | 'MASKING_POLICY_CHANGED'
+  /** 화면 마스킹 규칙의 선택자를 이 브라우저에서 적용할 수 없다. 다시 시도해도 같으므로 워크스페이스 관리자에게 문의한다. */
+  | 'MASKING_SELECTOR_UNSUPPORTED'
+  /** `createIssue()` 호출 한도(60초에 5건)를 넘었다. 한도 구간이 지난 뒤 다시 호출한다. */
+  | 'RATE_LIMITED';
 
 export type HeadlessAuthMode = 'public' | 'member';
 export type HeadlessCaptureMediaMode = 'screenshot' | 'video';
@@ -257,6 +286,28 @@ export interface HeadlessSessionReplayState {
   readonly error: string | null;
 }
 
+/** 뒤에서 올리는 영상 하나의 상태. 업로드가 끝나면 목록에서 빠집니다. */
+export interface HeadlessVideoUpload {
+  readonly issueId: string;
+  /** `failed` 는 네트워크 재시도를 모두 쓴 상태입니다. `retryVideoUpload()` 로 이어 올립니다. */
+  readonly status: 'queued' | 'uploading' | 'failed';
+  /** 0~1 */
+  readonly progress: number;
+}
+
+/** 뒤에서 올리는 세션 리플레이·웹소켓 로그 하나의 상태. 업로드가 끝나면 목록에서 빠집니다. */
+export interface HeadlessAttachmentUpload {
+  readonly issueId: string;
+  readonly kind: 'replay' | 'socket';
+  /**
+   * `failed` 는 네트워크 재시도를 모두 쓴 상태입니다. 연결이 돌아오거나 다음에 초기화할 때,
+   * 또는 `retryVideoUpload(issueId)` 를 부르면 다시 올립니다.
+   */
+  readonly status: 'queued' | 'uploading' | 'failed';
+  /** 0~1 */
+  readonly progress: number;
+}
+
 export interface HeadlessSnapshot {
   readonly phase: HeadlessPhase;
   readonly auth: HeadlessAuthState;
@@ -265,6 +316,8 @@ export interface HeadlessSnapshot {
   readonly draft: HeadlessIssueDraft | null;
   readonly videoCapture: HeadlessVideoCaptureState;
   readonly sessionReplay: HeadlessSessionReplayState;
+  readonly videoUploads: readonly HeadlessVideoUpload[];
+  readonly attachmentUploads: readonly HeadlessAttachmentUpload[];
   readonly formSchema: IssueFormSchema | null;
   readonly filterSchema: IssueFilterSchema | null;
   readonly error: IssueStickerHeadlessError | null;
@@ -313,6 +366,11 @@ export interface CreateIssueInput extends SubmitDraftInput {
   readonly target?: HTMLElement;
   /** 기본 `'screenshot'`. `'none'`이면 캡처를 건너뛰고 즉시 전송합니다. */
   readonly media?: 'screenshot' | 'none';
+  /**
+   * 이슈를 생성하지 않고 `null`로 끝날 때 한 번 호출됩니다. `code`는 `submitDraft()`가 던지는
+   * 코드와 같습니다. 이 콜백에서 던진 예외는 `createIssue()` 밖으로 전달되지 않습니다.
+   */
+  readonly onError?: (error: IssueStickerHeadlessError) => void;
 }
 
 export interface HeadlessClient {
@@ -329,18 +387,36 @@ export interface HeadlessClient {
   stopVideoCapture(): Promise<void>;
   setSessionReplayEnabled(enabled: boolean): void;
   cancelIssueCapture(): void;
-  submitDraft(input: SubmitDraftInput): Promise<Issue>;
+  /**
+   * 이슈를 생성하고 바로 돌려줍니다. 녹화 영상·세션 리플레이·웹소켓 로그는 이슈가 생성된 뒤
+   * 따로 업로드되며, 진행은 `snapshot.videoUploads`·`snapshot.attachmentUploads` 로 확인합니다.
+   *
+   * 프로젝트 마스킹 정책이 화면 녹화를 금지하면 영상 없이 이슈를 생성하고 `videoExcluded: true` 를
+   * 함께 돌려줍니다. 마스킹 정책을 적용하지 못해 스크린샷을 한 장이라도 첨부하지 않았으면
+   * `screenshotExcluded: true` 를 함께 돌려줍니다.
+   */
+  submitDraft(
+    input: SubmitDraftInput
+  ): Promise<Issue & { readonly videoExcluded?: boolean; readonly screenshotExcluded?: boolean }>;
+  /** 이슈의 실패한 업로드(영상·세션 리플레이·웹소켓 로그)를 다시 올립니다. */
+  retryVideoUpload(issueId: string): void;
   /**
    * 유저 액션 없이 코드에서 이슈를 만듭니다. 캡처 단계를 거치지 않으므로 `phase`와
    * `draft`를 건드리지 않고, 사용자가 이슈를 작성하는 중에도 호출할 수 있습니다.
    *
    * 실패해도 예외를 던지지 않고 `null`을 돌려줍니다. 이미 오류를 처리하는 자리에서
    * 부르는 메서드라, 이슈 생성만을 위한 try/catch 를 한 겹 더 쓰지 않아도 됩니다.
-   * 실패 사유는 콘솔 경고로 남습니다.
+   * 실패 사유는 콘솔 경고로 남고, `input.onError`가 있으면 그 에러로 호출됩니다.
    *
    * 호출 조건이 잘못 잡히면 이슈가 무한히 쌓이므로 SDK가 60초 5건으로 제한합니다.
+   * 넘어선 호출은 `RATE_LIMITED`로 끝납니다.
+   *
+   * 마스킹 정책을 적용하지 못해 스크린샷을 한 장이라도 첨부하지 않았으면 `screenshotExcluded: true` 를
+   * 함께 돌려줍니다.
    */
-  createIssue(input: CreateIssueInput): Promise<Issue | null>;
+  createIssue(
+    input: CreateIssueInput
+  ): Promise<(Issue & { readonly screenshotExcluded?: boolean }) | null>;
   loginAsMember(): Promise<void>;
   logoutMember(): Promise<void>;
   destroy(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issue-sticker",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "IssueSticker SDK - Visual bug tracking widget for web applications",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",