connectbase-client 3.8.1 → 3.10.0

package/dist/index.mjs

@@ -49,6 +49,40 @@ function createTimeoutController(options = {}) {
   };
 }
 
+// src/core/recent-calls.ts
+var DEFAULT_CAPACITY = 20;
+var MAX_CAPACITY = 50;
+var RecentCallsBuffer = class {
+  constructor(capacity = DEFAULT_CAPACITY) {
+    this.buf = [];
+    this.capacity = Math.min(Math.max(1, capacity), MAX_CAPACITY);
+  }
+  push(call) {
+    if (this.buf.length >= this.capacity) {
+      this.buf.shift();
+    }
+    this.buf.push(call);
+  }
+  /**
+   * 시간순(오래된 → 최신) 복사본 반환. 호출자가 mutate 해도 내부에 영향 없음.
+   */
+  snapshot() {
+    return this.buf.slice();
+  }
+  clear() {
+    this.buf = [];
+  }
+};
+function sanitizePathForBreadcrumb(rawUrl) {
+  try {
+    const u = rawUrl.startsWith("http") ? new URL(rawUrl) : new URL(rawUrl, "http://x");
+    return u.pathname || rawUrl;
+  } catch {
+    const idx = rawUrl.indexOf("?");
+    return idx >= 0 ? rawUrl.slice(0, idx) : rawUrl;
+  }
+}
+
 // src/core/http.ts
 var TOKEN_STORAGE_KEY = "cb_auth_tokens";
 var HttpClient = class {
@@ -59,11 +93,24 @@ var HttpClient = class {
     // 밀리초 단위로 서버에 재시도 요청이 쏟아지는 것을 차단.
     this.refreshFailureCount = 0;
     this.refreshLockedUntil = 0;
+    /**
+     * 최근 API 호출 breadcrumb (PII strip 후 저장). platform_issue 발행 시 자동 첨부 가능.
+     * `client.support.getRecentCalls()` 로 외부 노출.
+     */
+    this.recentCalls = new RecentCallsBuffer();
     this.config = { ...config };
     this.storageKey = this.buildStorageKey();
     this.warnIfUnsafePersistence();
     this.restoreTokens();
   }
+  /** 최근 호출 ring buffer 스냅샷 (시간순). */
+  getRecentCalls() {
+    return this.recentCalls.snapshot();
+  }
+  /** 최근 호출 buffer clear (테스트/프라이버시 처리). */
+  clearRecentCalls() {
+    this.recentCalls.clear();
+  }
   warnIfUnsafePersistence() {
     if (typeof window === "undefined") return;
     if (this.config.persistence === "localStorage") {
@@ -220,6 +267,7 @@ var HttpClient = class {
       const { signal, cleanup } = createTimeoutController({
         timeout: this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
       });
+      let failureKind = "transient";
       try {
         const headers = {
           "Content-Type": "application/json"
@@ -238,7 +286,28 @@ var HttpClient = class {
           signal
         });
         if (!response.ok) {
-          throw new Error("Token refresh failed");
+          const status = response.status;
+          let oauthError;
+          try {
+            const errBody = await response.clone().json();
+            if (errBody && typeof errBody.error === "string") {
+              oauthError = errBody.error;
+            } else if (errBody && typeof errBody.code === "string") {
+              oauthError = errBody.code;
+            }
+          } catch {
+          }
+          if (status >= 500) {
+            throw new Error(`Token refresh failed (${status})`);
+          }
+          if (status === 401 || status === 403 || status === 400 && (oauthError === "invalid_grant" || oauthError === "invalid_token")) {
+            failureKind = "permanent";
+          } else {
+            failureKind = "client_bug";
+          }
+          throw new Error(
+            `Token refresh failed (${status}${oauthError ? ` ${oauthError}` : ""})`
+          );
         }
         const data = await response.json();
         if (!data || typeof data.access_token !== "string") {
@@ -258,17 +327,35 @@ var HttpClient = class {
         this.refreshFailureCount = 0;
         this.refreshLockedUntil = 0;
         return data.access_token;
-      } catch {
+      } catch (e) {
+        const baseMsg = e instanceof Error ? e.message : "Token refresh failed";
         this.refreshFailureCount++;
         const backoffMs = Math.min(
           500 * 2 ** Math.max(0, this.refreshFailureCount - 1),
           3e4
         );
         this.refreshLockedUntil = Date.now() + backoffMs;
-        this.clearTokens();
-        this.config.onTokenExpired?.();
-        const error = new AuthError("Token refresh failed. Please login again.");
+        if (failureKind === "permanent") {
+          this.clearTokens();
+          this.config.onTokenExpired?.();
+          const error2 = new AuthError(`${baseMsg}. Please login again.`);
+          this.emitError(error2);
+          this.config.onAuthError?.(error2);
+          throw error2;
+        }
+        if (failureKind === "client_bug") {
+          const error2 = new AuthError(
+            `${baseMsg}. Client request invalid; tokens preserved.`
+          );
+          this.emitError(error2);
+          this.config.onAuthError?.(error2);
+          throw error2;
+        }
+        const error = new AuthError(
+          `${baseMsg}. Transient failure; tokens preserved, will retry after backoff.`
+        );
         this.emitError(error);
+        this.config.onTransientRefreshFailure?.(error);
         this.config.onAuthError?.(error);
         throw error;
       } finally {
@@ -397,14 +484,24 @@ var HttpClient = class {
       timeout: config?.timeout ?? this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
       signal: config?.signal
     });
+    const startedAt = Date.now();
+    let status = 0;
     try {
       const response = await fetch(`${this.config.baseUrl}${url}`, {
         ...init,
         credentials: "include",
         signal
       });
+      status = response.status;
       return await this.handleResponse(response);
     } finally {
+      this.recentCalls.push({
+        method: (init.method || "GET").toUpperCase(),
+        path: sanitizePathForBreadcrumb(url),
+        status,
+        duration_ms: Date.now() - startedAt,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
       cleanup();
     }
   }
@@ -8358,8 +8455,8 @@ var AnalyticsAPI = class {
    * @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) {
@@ -8941,6 +9038,174 @@ var AnalyticsAPI = class {
   }
 };
 
+// src/api/support.ts
+var SupportAPI = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 앱 운영자에게 이슈/문의/요청을 발행한다.
+   *
+   * 로그인된 사용자(AppMember)면 신뢰 등급이 높고 reporter_member_id 가 자동으로 채워진다.
+   * 익명 발행도 가능하나 운영자가 reCAPTCHA 를 활성화한 경우 `recaptchaToken` 이 권장된다.
+   *
+   * @returns 발행된 이슈 id + 초기 status (`open`) + 생성 시각.
+   * @throws ApiError — 본문 길이 초과 / 쿼터 초과(429) / reCAPTCHA 거부(403) 등.
+   */
+  async reportIssue(req) {
+    const body = {
+      title: req.title,
+      body: req.body,
+      category: req.category,
+      metadata: req.metadata
+    };
+    if (req.anonymousEmail) body.anonymous_email = req.anonymousEmail;
+    if (req.recaptchaToken) body.recaptcha_token = req.recaptchaToken;
+    return this.http.post("/v1/public/reports", body);
+  }
+  /**
+   * 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,
+   *   })
+   * }
+   * ```
+   */
+  async reportPlatformBug(req) {
+    const attachContext = req.attachAutomaticContext !== false;
+    const body = {
+      title: req.title,
+      body: req.body,
+      category: req.category ?? "other",
+      severity: req.severity ?? "medium",
+      metadata: req.metadata
+    };
+    if (req.reporterEmail) body.reporter_email = req.reporterEmail;
+    if (req.recaptchaToken) body.recaptcha_token = req.recaptchaToken;
+    if (attachContext) {
+      body.sdk_version = req.sdkVersion ?? detectSdkVersion();
+      body.sdk_platform = req.sdkPlatform ?? detectSdkPlatform();
+      body.environment = req.environment ?? "unknown";
+      if (req.error) {
+        body.stack_trace = sanitizeStackTrace(req.error.stack ?? String(req.error));
+      } else if (req.stackTrace) {
+        body.stack_trace = sanitizeStackTrace(req.stackTrace);
+      }
+      const calls = req.recentApiCalls ?? this.http.getRecentCalls();
+      if (calls.length > 0) {
+        body.recent_api_calls = calls;
+      }
+    }
+    return this.http.post(
+      "/v1/public/platform-issues",
+      body
+    );
+  }
+  /** 디버깅용: 마지막 N개 API 호출 breadcrumb. PII 제거 후 저장돼있다. */
+  getRecentApiCalls() {
+    return this.http.getRecentCalls();
+  }
+  /** breadcrumb buffer 비우기 (사용자 명시적 요청 / 프라이버시). */
+  clearRecentApiCalls() {
+    this.http.clearRecentCalls();
+  }
+  /**
+   * Platform issue 의 reply thread 조회.
+   *
+   * 본인이 발행한 issue 만 조회 가능 (server-side ownership guard). admin 의 internal 메모는 응답 제외.
+   *
+   * @param issueId - `reportPlatformBug` 가 반환한 id
+   * @throws ApiError 404 — 본인 issue 가 아니거나 존재하지 않음
+   */
+  async listPlatformIssueReplies(issueId) {
+    const res = await this.http.get(
+      `/v1/public/platform-issues/${issueId}/comments`
+    );
+    return res.comments;
+  }
+  /**
+   * Platform issue 에 follow-up reply 작성.
+   *
+   * 단말 상태(resolved/wontfix/duplicate) issue 는 reply 거부 — 새 issue 발행 권장.
+   */
+  async replyToPlatformIssue(issueId, body) {
+    return this.http.post(
+      `/v1/public/platform-issues/${issueId}/comments`,
+      { body }
+    );
+  }
+  /**
+   * 본인이 발행한 platform issue 의 처리 진행 상황을 단건 조회.
+   *
+   * AI 가 "내가 발행한 이슈 처리됐어?" 를 폴링하는 표준 경로. status / resolution_note /
+   * triage_summary / external_links 로 ConnectBase 운영팀의 처리 상태를 확인.
+   *
+   * @throws ApiError 404 — 본인 issue 가 아니거나 존재하지 않음
+   */
+  async getPlatformIssue(issueId) {
+    return this.http.get(
+      `/v1/public/platform-issues/${issueId}`
+    );
+  }
+  /**
+   * 본인 app 으로 발행한 platform issue 목록 (cursor 페이지네이션).
+   *
+   * status/severity/category 필터 + `since_updated_at` 으로 미해결만 폴링하는 사용 패턴 권장:
+   *
+   * ```typescript
+   * const { issues } = await cb.support.listMyPlatformIssues({ status: ['open', 'triaged', 'in_progress'] })
+   * ```
+   */
+  async listMyPlatformIssues(opts = {}) {
+    const params = new URLSearchParams();
+    for (const s of opts.status ?? []) params.append("status", s);
+    for (const s of opts.severity ?? []) params.append("severity", s);
+    for (const s of opts.category ?? []) params.append("category", s);
+    if (opts.sinceUpdatedAt) params.set("since_updated_at", opts.sinceUpdatedAt);
+    if (opts.cursor) params.set("cursor", opts.cursor);
+    if (typeof opts.limit === "number") params.set("limit", String(opts.limit));
+    const query = params.toString();
+    return this.http.get(
+      `/v1/public/platform-issues${query ? "?" + query : ""}`
+    );
+  }
+};
+function detectSdkVersion() {
+  if (typeof __SDK_VERSION__ !== "undefined" && __SDK_VERSION__) {
+    return __SDK_VERSION__;
+  }
+  return "unknown";
+}
+function detectSdkPlatform() {
+  return typeof window !== "undefined" && typeof document !== "undefined" ? "web" : "node";
+}
+function sanitizeStackTrace(raw) {
+  let s = raw;
+  s = s.replace(/(\(|\s|^)(?:file:\/\/)?\/[^\s)]+\/([^\s/)]+)(:\d+:\d+)?/g, "$1$2$3");
+  s = s.replace(/(https?:\/\/[^\s)?]+)\?[^\s)]*/g, "$1");
+  const max = 32 * 1024;
+  if (s.length > max) s = s.slice(0, max) + "\n\u2026[truncated]";
+  return s;
+}
+
 // src/types/knowledge.ts
 var AUTH_MEMBER_ID_TOKEN = "$auth.member_id";
 
@@ -9605,7 +9870,8 @@ var ConnectBase = class {
       onError: config.onError,
       onTokenRefresh: config.onTokenRefresh,
       onAuthError: config.onAuthError,
-      onTokenExpired: config.onTokenExpired
+      onTokenExpired: config.onTokenExpired,
+      onTransientRefreshFailure: config.onTransientRefreshFailure
     };
     this.http = new HttpClient(httpConfig);
     this.auth = new AuthAPI(this.http);
@@ -9629,6 +9895,7 @@ var ConnectBase = class {
     this.queue = new QueueAPI(this.http);
     this.analytics = new AnalyticsAPI(this.http);
     this.endpoint = new EndpointAPI(this.http);
+    this.support = new SupportAPI(this.http);
     this.auth._attachAnalytics(this.analytics);
     const shouldAutoRestore = config.autoRestoreSession ?? true;
     if (shouldAutoRestore && typeof window !== "undefined") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "3.8.1",
+  "version": "3.10.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",