Viewthread SDK

Korean follows English.

English

Viewthread SDK adds snapshot capture and collaborative review to your web app with a simple integration. It captures DOM + screenshots, collects useful logs, and uploads them to your Viewthread server for team discussion and issue tracking.

• Website: https://viewthread.site
• Package: @viewthread/sdk

Installation

npm install @viewthread/sdk
# peer deps are bundled; TypeScript is recommended but not required

Minimal example

import { ViewthreadSDK } from '@viewthread/sdk';

const vt = new ViewthreadSDK({
  apiKey: process.env.VIEWTHREAD_API_KEY!,
  apiUrl: 'https://api.viewthread.site',
  // websocketUrl: 'wss://ws.viewthread.site' // optional
});

await vt.init();
const snapshotId = await vt.captureSnapshot('Homepage', 'Smoke test');
console.log('Snapshot:', snapshotId);

Configuration

export interface ViewthreadSDKConfig {
  apiKey: string;                  // required: JWT or API key
  apiUrl?: string;                 // default: https://api.viewthread.site
  websocketUrl?: string;           // optional
  projectId?: string;              // resolved automatically from token if omitted
  selectionEnabled?: boolean;      // enable region selection (default false)
  autoCapture?: boolean;           // auto start log capture (default true)
  captureConsole?: boolean;        // default true
  captureNetwork?: boolean;        // default false
  captureUserActions?: boolean;    // default true
  maskSensitiveData?: boolean;     // default true
  sensitiveDataSelectors?: string[];
  maxLogSize?: number;             // default 1000
  uploadChunkSize?: number;        // default 1MB
  retryAttempts?: number;          // default 3
  debug?: boolean;                 // verbose logs
  onAuthRequired?: () => Promise<string | null>; // custom auth flow
}

Defaults come from @viewthread/shared (DEFAULT_CONFIG).

Public API

• new ViewthreadSDK(config)
  • init(): Promise<void>: validates key, wires up auto capture, injects UI button
  • captureSnapshot(title?: string, description?: string): Promise<string>
  • reportIssue(title: string, description: string, labels?: string[]): Promise<{ snapshotId: string; issueUrl?: string }>
  • cleanup(): void
  • isCapturing(): boolean
• Module exports for power users
  • ActionLogger, DOMCapture, NetworkCapture, ConsoleCapture, Uploader
  • Utilities and types from @viewthread/shared

Advanced usage

• Region capture: selectionEnabled: true enables drag-to-select cropping.
• Auth flow: provide onAuthRequired to integrate your own login UI. The SDK will cache JWT in localStorage (viewthread_token).
• GitHub issues: if your project is connected to GitHub on the server, reportIssue() will return the created issue URL.
• Proxying external images: the SDK temporarily rewrites image URLs to GET /api/v1/proxy/image?url= during screenshot for CORS safety.

TypeScript usage

Types are exported from @viewthread/shared:

import type { Snapshot, UploadProgress } from '@viewthread/shared';

Examples

• Manual capture on a button click

const button = document.getElementById('capture');
button?.addEventListener('click', async () => {
  try {
    const id = await vt.captureSnapshot('Manual', 'User requested');
    alert(`Captured: ${id}`);
  } catch (e) {
    console.error(e);
  }
});

• Report modal (built-in): the floating bug button opens a minimal modal to submit reports.

Troubleshooting

• 401/403 on upload: provide a valid apiKey. If it expires, implement onAuthRequired.
• Blank screenshot of cross-origin images: ensure your server proxy endpoint is reachable (/api/v1/proxy/image).
• Very large pages: tune uploadChunkSize (e.g., 2–4 MB) and increase server limits if needed.

Versioning

• Follow SemVer. Breaking changes bump the major version.

한국어

Viewthread SDK는 웹앱에 스냅샷 캡처와 협업 리뷰 기능을 간단히 추가합니다. DOM과 스크린샷을 함께 캡처하고, 로그를 수집해 서버로 업로드하여 팀이 토론하고 이슈를 관리할 수 있게 돕습니다.

• 홈페이지: https://viewthread.site
• 패키지: @viewthread/sdk

설치

npm install @viewthread/sdk

최소 예제

import { ViewthreadSDK } from '@viewthread/sdk';

const sdk = new ViewthreadSDK({
  apiKey: '발급_API_KEY',
  apiUrl: 'https://api.viewthread.site',
});

await sdk.init();
const snapshotId = await sdk.captureSnapshot('홈', '첫 캡처');

설정값

• apiKey(필수): JWT 또는 API 키
• apiUrl(기본 https://api.viewthread.site), websocketUrl(선택)
• projectId(선택): 미지정 시 토큰에서 자동 해석 시도
• 캡처/로그 옵션: autoCapture, captureConsole, captureNetwork, captureUserActions
• 보안/품질: maskSensitiveData, sensitiveDataSelectors, maxLogSize, uploadChunkSize, retryAttempts
• 디버그/인증: debug, onAuthRequired

제공 API

• init(), captureSnapshot(title?, description?), reportIssue(title, description, labels?), cleanup(), isCapturing()
• 고급 사용자용 모듈/유틸: ActionLogger, DOMCapture, NetworkCapture, ConsoleCapture, Uploader, @viewthread/shared의 타입/상수/유틸

고급 주제

• 영역 캡처: selectionEnabled: true 설정
• 사용자 인증 연동: onAuthRequired 구현 시, SDK가 로컬스토리지에 JWT 저장/복구
• GitHub 이슈: 서버에서 프로젝트 연동된 경우 reportIssue()가 이슈 URL을 반환
• 외부 이미지 CORS: 캡처 중 임시로 프록시(GET /api/v1/proxy/image) 사용

문제 해결

• 업로드 401/403: 유효한 apiKey 제공, 만료 시 onAuthRequired 구현
• 스크린샷이 비어있음: 프록시 엔드포인트 접근 가능 여부 확인
• 대용량 페이지: uploadChunkSize를 2–4MB로 조정, 서버 업로드 한도 확인

버전 규칙

• SemVer를 따르며, 파괴적 변경 시 major 버전을 올립니다.

For more examples and server API, visit our website.