connectbase-client 3.8.1 → 3.10.0

package/dist/index.d.ts

@@ -18,6 +18,23 @@ interface AbortOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * Recent API calls breadcrumb buffer — SDK 디버깅 / platform issue 발행 시 자동 첨부.
+ *
+ * **저장 정책 (PII 보호):**
+ *   - method, path (query string strip), status, duration_ms, timestamp 만 저장
+ *   - body / response body / 인증 토큰 미저장
+ *   - URL 내 secret-like 패턴 (key=, token=, password=) 자동 redact
+ *   - `/v1/auth/*`, `/v1/oauth/token` 등 민감 endpoint 는 path 만 (쿼리 strip)
+ */
+interface RecentApiCall {
+    method: string;
+    path: string;
+    status: number;
+    duration_ms: number;
+    timestamp: string;
+}
+
 type TokenPersistence = 'localStorage' | 'sessionStorage' | 'none';
 interface HttpClientConfig {
     baseUrl: string;
@@ -68,6 +85,13 @@ interface HttpClientConfig {
     }) => void;
     onAuthError?: (error: AuthError) => void;
     onTokenExpired?: () => void;
+    /**
+     * `/v1/auth/re-issue` 의 일시적 실패(5xx, 네트워크 오류, abort) 발생 시 호출.
+     * 이 경우 토큰은 폐기되지 않으며 `onTokenExpired` 도 호출되지 않는다 — 다음 호출에서
+     * backoff 만료 후 자동 재시도. 사용자에게 "연결이 잠시 불안정합니다" 같은 비파괴적 알림을
+     * 표시할 때 사용. `onAuthError` 도 함께 호출되므로 둘을 동시에 wiring 하면 중복 처리에 주의.
+     */
+    onTransientRefreshFailure?: (error: AuthError) => void;
 }
 interface RequestConfig extends AbortOptions {
     skipAuth?: boolean;
@@ -80,7 +104,16 @@ declare class HttpClient {
     private storageKey;
     private refreshFailureCount;
     private refreshLockedUntil;
+    /**
+     * 최근 API 호출 breadcrumb (PII strip 후 저장). platform_issue 발행 시 자동 첨부 가능.
+     * `client.support.getRecentCalls()` 로 외부 노출.
+     */
+    private recentCalls;
     constructor(config: HttpClientConfig);
+    /** 최근 호출 ring buffer 스냅샷 (시간순). */
+    getRecentCalls(): RecentApiCall[];
+    /** 최근 호출 buffer clear (테스트/프라이버시 처리). */
+    clearRecentCalls(): void;
     private warnIfUnsafePersistence;
     updateConfig(config: Partial<HttpClientConfig>): void;
     setTokens(accessToken: string, refreshToken: string): void;
@@ -409,8 +442,8 @@ declare class AnalyticsAPI {
      * @example
      * ```ts
      * // 로그인 성공 직후
-     * await cb.auth.signIn({ email, password })
-     * cb.analytics.identify(member.id)
+     * const member = await cb.auth.signInMember({ login_id, password })
+     * cb.analytics.identify(member.member_id)
      * ```
      */
     identify(memberId: string): void;
@@ -7228,6 +7261,280 @@ declare class QueueAPI {
     getInfo(queueID: string): Promise<QueueInfoResponse>;
 }
 
+/**
+ * 사용자 제보 (end-user issue) — 카테고리.
+ *
+ * - `bug` 버그 리포트
+ * - `question` 질문/문의
+ * - `feature_request` 기능 요청
+ * - `incident` 긴급 장애
+ * - `other` 그 외
+ */
+type SupportIssueCategory = 'bug' | 'question' | 'feature_request' | 'incident' | 'other';
+/**
+ * 제보 발행 요청 본문.
+ */
+interface ReportIssueRequest {
+    /** 제목 (최대 200자) */
+    title: string;
+    /** 본문 (최대 16KB, 마크다운) */
+    body: string;
+    /** 카테고리. 기본값 `other`. AI 가 자동 보정해 줌. */
+    category?: SupportIssueCategory;
+    /** 자유 컨텍스트 (페이지 URL, 앱 버전, trace_id 등) */
+    metadata?: Record<string, unknown>;
+    /**
+     * 익명 발행 시 회신 받을 이메일 (선택).
+     * 로그인된 사용자면 무시되고 AppMember 정보로 대체.
+     */
+    anonymousEmail?: string;
+    /**
+     * Google reCAPTCHA v3 토큰. 익명 발행 + 운영자가 reCAPTCHA 활성화한 앱은 권장.
+     * 미주입 시 score=0 으로 처리 — 거부될 수 있음.
+     */
+    recaptchaToken?: string;
+}
+/**
+ * 제보 발행 응답. 보안상 최소 정보만 (id + status + created_at).
+ */
+interface ReportIssueResponse {
+    id: string;
+    status: 'open';
+    created_at: string;
+}
+/**
+ * Support API — 사용자 제보 (end-user issue) 발행.
+ *
+ * 사용자가 앱 운영자에게 직접 버그/질문/요청을 보내는 채널. AppMember JWT 가 있으면
+ * 강 신뢰로 회신 가능, 없으면 익명 발행 (reCAPTCHA 권장).
+ *
+ * 발행된 이슈는 운영자 콘솔의 inbox 에 들어가며, AI 가 자동으로 요약/긴급도/카테고리를
+ * 분류해줘 운영자/AI 의 처리 효율을 높여준다.
+ *
+ * @example 로그인 사용자가 버그 리포트
+ * ```typescript
+ * // (cb.auth.signIn 으로 로그인 완료된 상태)
+ * await cb.support.reportIssue({
+ *     title: "결제 화면이 멈춰요",
+ *     body: "결제 버튼 클릭 후 로딩이 끝나지 않습니다.",
+ *     category: "bug",
+ *     metadata: { pageUrl: window.location.href, browser: navigator.userAgent },
+ * })
+ * ```
+ *
+ * @example 익명 + reCAPTCHA v3
+ * ```typescript
+ * // window.grecaptcha 는 reCAPTCHA v3 site script 로드 후 전역으로 노출됨
+ * const grecaptcha = (globalThis as any).grecaptcha
+ * const SITE_KEY = "your-recaptcha-site-key"
+ * const token = await grecaptcha.execute(SITE_KEY, { action: 'report_issue' })
+ * await cb.support.reportIssue({
+ *     title: "버그 제보",
+ *     body: "익명으로 제보합니다",
+ *     category: "question",
+ *     anonymousEmail: "user@example.com",
+ *     recaptchaToken: token,
+ * })
+ * ```
+ */
+declare class SupportAPI {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * 앱 운영자에게 이슈/문의/요청을 발행한다.
+     *
+     * 로그인된 사용자(AppMember)면 신뢰 등급이 높고 reporter_member_id 가 자동으로 채워진다.
+     * 익명 발행도 가능하나 운영자가 reCAPTCHA 를 활성화한 경우 `recaptchaToken` 이 권장된다.
+     *
+     * @returns 발행된 이슈 id + 초기 status (`open`) + 생성 시각.
+     * @throws ApiError — 본문 길이 초과 / 쿼터 초과(429) / reCAPTCHA 거부(403) 등.
+     */
+    reportIssue(req: ReportIssueRequest): Promise<ReportIssueResponse>;
+    /**
+     * ConnectBase 플랫폼 자체 버그/요청/문의를 발행한다.
+     *
+     * `reportIssue` 와 다른 점: target 이 앱 운영자가 아닌 **ConnectBase 운영팀**.
+     * SDK 가 자체 버그를 던지거나, 결제/문서/플랫폼 동작이 이상할 때 사용.
+     *
+     * 자동 첨부 (opt-out 가능):
+     *   - SDK 버전 + 플랫폼 (web/node)
+     *   - 마지막 N(20)개 API 호출 breadcrumb (PII strip 후)
+     *   - error 객체의 stack trace (sanitize)
+     *
+     * @example SDK 가 throw 한 에러를 자동 첨부해서 발행
+     * ```typescript
+     * try {
+     *   await cb.functions.invoke('foo', {})
+     * } catch (err) {
+     *   await cb.support.reportPlatformBug({
+     *     title: 'functions.invoke 가 504 만 반환',
+     *     body: '같은 인자로 5분 째 504. 콘솔에선 정상.',
+     *     category: 'sdk',
+     *     severity: 'high',
+     *     error: err as Error,
+     *   })
+     * }
+     * ```
+     */
+    reportPlatformBug(req: ReportPlatformBugRequest): Promise<ReportPlatformBugResponse>;
+    /** 디버깅용: 마지막 N개 API 호출 breadcrumb. PII 제거 후 저장돼있다. */
+    getRecentApiCalls(): RecentApiCall[];
+    /** breadcrumb buffer 비우기 (사용자 명시적 요청 / 프라이버시). */
+    clearRecentApiCalls(): void;
+    /**
+     * Platform issue 의 reply thread 조회.
+     *
+     * 본인이 발행한 issue 만 조회 가능 (server-side ownership guard). admin 의 internal 메모는 응답 제외.
+     *
+     * @param issueId - `reportPlatformBug` 가 반환한 id
+     * @throws ApiError 404 — 본인 issue 가 아니거나 존재하지 않음
+     */
+    listPlatformIssueReplies(issueId: string): Promise<PlatformIssueReply[]>;
+    /**
+     * Platform issue 에 follow-up reply 작성.
+     *
+     * 단말 상태(resolved/wontfix/duplicate) issue 는 reply 거부 — 새 issue 발행 권장.
+     */
+    replyToPlatformIssue(issueId: string, body: string): Promise<PlatformIssueReply>;
+    /**
+     * 본인이 발행한 platform issue 의 처리 진행 상황을 단건 조회.
+     *
+     * AI 가 "내가 발행한 이슈 처리됐어?" 를 폴링하는 표준 경로. status / resolution_note /
+     * triage_summary / external_links 로 ConnectBase 운영팀의 처리 상태를 확인.
+     *
+     * @throws ApiError 404 — 본인 issue 가 아니거나 존재하지 않음
+     */
+    getPlatformIssue(issueId: string): Promise<PlatformIssueDetail>;
+    /**
+     * 본인 app 으로 발행한 platform issue 목록 (cursor 페이지네이션).
+     *
+     * status/severity/category 필터 + `since_updated_at` 으로 미해결만 폴링하는 사용 패턴 권장:
+     *
+     * ```typescript
+     * const { issues } = await cb.support.listMyPlatformIssues({ status: ['open', 'triaged', 'in_progress'] })
+     * ```
+     */
+    listMyPlatformIssues(opts?: ListMyPlatformIssuesOptions): Promise<PlatformIssueListPage>;
+}
+/**
+ * ConnectBase 플랫폼 이슈 카테고리.
+ */
+type PlatformIssueCategory = 'bug' | 'feature_request' | 'sdk' | 'billing' | 'security' | 'performance' | 'docs' | 'other';
+type PlatformIssueSeverity = 'low' | 'medium' | 'high' | 'critical';
+interface ReportPlatformBugRequest {
+    /** 제목 (≤200) */
+    title: string;
+    /** 본문 (≤16KB, markdown) */
+    body: string;
+    /** 카테고리. 기본 `other`. AI triage 가 보정. */
+    category?: PlatformIssueCategory;
+    /** 긴급도. 기본 `medium`. AI triage 가 보정. */
+    severity?: PlatformIssueSeverity;
+    /** AppMember 가 없는 경우 회신용 이메일. */
+    reporterEmail?: string;
+    /** 익명 발행 시 reCAPTCHA v3 토큰 (운영팀이 RECAPTCHA_SECRET 설정한 경우). */
+    recaptchaToken?: string;
+    /** 자유 컨텍스트 (페이지 URL, request_id 등). PII 직접 포함 금지 — 호출자 책임. */
+    metadata?: Record<string, unknown>;
+    /**
+     * 자동 컨텍스트 첨부 on/off (기본 true).
+     * false 로 설정하면 SDK 버전/플랫폼/breadcrumb/stack 모두 미첨부.
+     */
+    attachAutomaticContext?: boolean;
+    /**
+     * 에러 객체. .stack 을 sanitize 후 자동 첨부.
+     * stackTrace 와 둘 중 하나만 — error 가 우선.
+     */
+    error?: Error;
+    /** 직접 작성한 stack trace (≤32KB, SDK 가 sanitize). */
+    stackTrace?: string;
+    /** 호출자가 명시적으로 buffer 를 override (테스트/특수 케이스). */
+    recentApiCalls?: RecentApiCall[];
+    /** SDK 버전 override (자동 감지 실패 시). */
+    sdkVersion?: string;
+    /** SDK 플랫폼 override. */
+    sdkPlatform?: 'web' | 'node' | 'unity' | 'godot' | 'unreal' | 'cli' | 'mcp' | 'other';
+    /** 환경 (production/staging/development). 기본 unknown. */
+    environment?: 'production' | 'staging' | 'development' | 'unknown';
+}
+interface ReportPlatformBugResponse {
+    id: string;
+    status: 'open';
+    created_at: string;
+}
+/**
+ * Platform issue thread 의 단일 reply.
+ *
+ * - `author_kind=admin`: ConnectBase 운영팀 응답
+ * - `author_kind=user`: 본인이 작성
+ * - `author_kind=system`: 자동 메시지 (상태 변경 알림 등)
+ */
+/**
+ * Platform issue 의 처리 진행 상황 (reporter 시점).
+ *
+ * admin-only 필드(`assignee_user_id`, internal triage signal) 는 server 가 redact.
+ *
+ * 주요 필드:
+ *   - `status`           : `open` → `triaged` → `in_progress` → `resolved` | `wontfix` | `duplicate`
+ *   - `resolution_note`  : 단말 상태 진입 시 ConnectBase 운영팀이 작성한 처리 결과 (markdown)
+ *   - `triage_summary`   : AI triage 가 작성한 1줄 요약
+ *   - `external_links`   : 운영팀이 연결한 GitHub PR / Linear ticket 등
+ *   - `resolved_at`      : `resolved`/`wontfix` 진입 시각 (해결됐는지 빠른 검사용)
+ */
+interface PlatformIssueDetail {
+    id: string;
+    reporter_kind: 'user' | 'app' | 'system';
+    title: string;
+    body: string;
+    category: PlatformIssueCategory;
+    severity: PlatformIssueSeverity;
+    status: 'open' | 'triaged' | 'in_progress' | 'resolved' | 'wontfix' | 'duplicate';
+    resolution_note?: string;
+    sdk_version?: string;
+    sdk_platform?: 'web' | 'node' | 'unity' | 'godot' | 'unreal' | 'cli' | 'mcp' | 'other';
+    environment?: 'production' | 'staging' | 'development' | 'unknown';
+    triage_summary?: string;
+    triaged_at?: string;
+    external_links?: Array<{
+        kind: string;
+        url: string;
+        label?: string;
+    }>;
+    duplicate_of_id?: string;
+    created_at: string;
+    updated_at: string;
+    resolved_at?: string;
+}
+/** `listMyPlatformIssues` 응답 페이지. */
+interface PlatformIssueListPage {
+    issues: PlatformIssueDetail[];
+    /** 다음 페이지 cursor. 빈 문자열/undefined 면 끝. */
+    next_cursor?: string;
+}
+/** `listMyPlatformIssues` 옵션. */
+interface ListMyPlatformIssuesOptions {
+    /** 다중 status 필터. 미지정 시 전체. 처리중만 보려면 `['open','triaged','in_progress']`. */
+    status?: PlatformIssueDetail['status'][];
+    severity?: PlatformIssueSeverity[];
+    category?: PlatformIssueCategory[];
+    /** RFC3339 timestamp — 이후 update 된 issue 만. polling 시 마지막 fetch 시각 전달. */
+    sinceUpdatedAt?: string;
+    /** 이전 페이지 응답의 `next_cursor`. */
+    cursor?: string;
+    /** 페이지 크기. 기본 50, 최대 200. */
+    limit?: number;
+}
+interface PlatformIssueReply {
+    id: string;
+    issue_id: string;
+    author_kind: 'admin' | 'user' | 'system';
+    author_user_id?: string;
+    author_member_id?: string;
+    body: string;
+    is_internal: boolean;
+    created_at: string;
+}
+
 /**
  * WebTransport-based Game Client
  *
@@ -7437,6 +7744,23 @@ interface ConnectBaseConfig {
      * ```
      */
     onTokenExpired?: () => void;
+    /**
+     * `/v1/auth/re-issue` 의 일시적 실패 (5xx, 네트워크 오류, abort, 손상된 200 응답) 시 호출.
+     *
+     * 이 경우 토큰은 폐기되지 않으며 `onTokenExpired` 도 호출되지 않습니다 — 다음 호출에서
+     * backoff 만료 후 자동 재시도. 사용자에게 "연결이 잠시 불안정합니다" 같은 비파괴적
+     * 알림을 띄울 때 사용. permanent (refresh token 자체 무효) 와 분리하기 위함.
+     *
+     * @example
+     * ```typescript
+     * const cb = new ConnectBase({
+     *     publicKey: '...',
+     *     onTransientRefreshFailure: (err) => toast.warn('연결이 불안정합니다. 잠시 후 자동 복구됩니다.'),
+     *     onTokenExpired: () => { window.location.href = '/login' },
+     * })
+     * ```
+     */
+    onTransientRefreshFailure?: (error: Error) => void;
     /**
      * 토큰 저장 방식.
      * - 'none' (기본·권장): access token 만 메모리. refresh token 은 서버 HttpOnly cookie 로
@@ -7607,6 +7931,11 @@ declare class ConnectBase {
      * 한 키로 호출. 라벨로 라우팅, 페이로드/응답은 그대로 통과.
      */
     readonly endpoint: EndpointAPI;
+    /**
+     * Support API (사용자 제보 / 이슈 큐)
+     * 앱 사용자가 운영자에게 버그/질문/요청을 발행. AI 가 자동 분류/우선순위 처리.
+     */
+    readonly support: SupportAPI;
     constructor(config?: ConnectBaseConfig);
     /**
      * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).