connectbase-client 3.30.0 → 3.32.0

package/dist/index.d.mts

@@ -3847,6 +3847,12 @@ declare function escapeToExternalBrowser(currentUrl?: string): boolean;
  */
 declare class OAuthAPI {
     private http;
+    /**
+     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
+     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
+     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
+     */
+    private bootConsumePromise;
     constructor(http: HttpClient);
     /**
      * 활성화된 OAuth 프로바이더 목록 조회
@@ -3971,6 +3977,28 @@ declare class OAuthAPI {
         state?: string;
         error?: string;
     } | null>;
+    /**
+     * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
+     *
+     * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
+     * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
+     * 적재해 세션을 확립한다.
+     *
+     * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
+     * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
+     * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
+     * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
+     *
+     * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
+     * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
+     * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
+     * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
+     * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+     *
+     * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
+     */
+    consumeRedirectCallbackOnBoot(): Promise<boolean>;
+    private doConsumeRedirectOnBoot;
     /**
      * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
      *
@@ -7515,6 +7543,21 @@ interface AIChatRequest {
     topK?: number;
     agentic?: boolean;
     toolGroupId?: string;
+    /**
+     * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에
+     * **재투입하기 전** N 자(rune 기준)로 잘라낸다(말미에 잘림 표시). SSE `onToolEvent` 의
+     * `tool_end.result` 로 표시되는 값은 원문을 유지한다.
+     *
+     * 거대한 도구 결과(예: 복잡한 페이지의 `browser_snapshot`)가 누적 컨텍스트를 부풀려
+     * 매 턴 prefill 을 무겁게 만들 때, 표시는 원문으로 두고 모델 재투입분만 압축해
+     * 지연을 줄이는 용도. 미지정/0 이면 자르지 않는다.
+     */
+    toolResultMaxChars?: number;
+    /**
+     * 요청에 포함한 MCP 도구(`tools`)를 호출할 외부 MCP 서버의 Public Key (cb_pk_* 형식).
+     * MCP 도구를 직접 넘기지 않으면 불필요하다.
+     */
+    mcpPublicKey?: string;
 }
 /**
  * `chatStream` 콜백.
@@ -8812,9 +8855,18 @@ declare class ConnectBase {
      *
      * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
      * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-     * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+     * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
      */
     private isOAuthCallbackUrl;
+    /**
+     * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
+     *
+     * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
+     * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
+     * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
+     * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
+     */
+    private isOAuthRedirectCallbackUrl;
     /**
      * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
      *

package/dist/index.d.ts

@@ -3847,6 +3847,12 @@ declare function escapeToExternalBrowser(currentUrl?: string): boolean;
  */
 declare class OAuthAPI {
     private http;
+    /**
+     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
+     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
+     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
+     */
+    private bootConsumePromise;
     constructor(http: HttpClient);
     /**
      * 활성화된 OAuth 프로바이더 목록 조회
@@ -3971,6 +3977,28 @@ declare class OAuthAPI {
         state?: string;
         error?: string;
     } | null>;
+    /**
+     * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
+     *
+     * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
+     * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
+     * 적재해 세션을 확립한다.
+     *
+     * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
+     * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
+     * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
+     * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
+     *
+     * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
+     * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
+     * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
+     * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
+     * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+     *
+     * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
+     */
+    consumeRedirectCallbackOnBoot(): Promise<boolean>;
+    private doConsumeRedirectOnBoot;
     /**
      * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
      *
@@ -7515,6 +7543,21 @@ interface AIChatRequest {
     topK?: number;
     agentic?: boolean;
     toolGroupId?: string;
+    /**
+     * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에
+     * **재투입하기 전** N 자(rune 기준)로 잘라낸다(말미에 잘림 표시). SSE `onToolEvent` 의
+     * `tool_end.result` 로 표시되는 값은 원문을 유지한다.
+     *
+     * 거대한 도구 결과(예: 복잡한 페이지의 `browser_snapshot`)가 누적 컨텍스트를 부풀려
+     * 매 턴 prefill 을 무겁게 만들 때, 표시는 원문으로 두고 모델 재투입분만 압축해
+     * 지연을 줄이는 용도. 미지정/0 이면 자르지 않는다.
+     */
+    toolResultMaxChars?: number;
+    /**
+     * 요청에 포함한 MCP 도구(`tools`)를 호출할 외부 MCP 서버의 Public Key (cb_pk_* 형식).
+     * MCP 도구를 직접 넘기지 않으면 불필요하다.
+     */
+    mcpPublicKey?: string;
 }
 /**
  * `chatStream` 콜백.
@@ -8812,9 +8855,18 @@ declare class ConnectBase {
      *
      * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
      * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-     * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+     * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
      */
     private isOAuthCallbackUrl;
+    /**
+     * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
+     *
+     * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
+     * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
+     * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
+     * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
+     */
+    private isOAuthRedirectCallbackUrl;
     /**
      * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
      *

package/dist/index.js

@@ -153,6 +153,10 @@ function sanitizePathForBreadcrumb(rawUrl) {
 }
 
 // src/core/http.ts
+function fetchCredentialsForPath(url) {
+  const path = url.split("?")[0];
+  return path.startsWith("/v1/public/") ? "omit" : "include";
+}
 var TOKEN_STORAGE_KEY = "cb_auth_tokens";
 function decodeJwtPayload(token) {
   try {
@@ -679,7 +683,7 @@ var HttpClient = class {
     try {
       const response = await fetch(`${this.config.baseUrl}${url}`, {
         ...init,
-        credentials: "include",
+        credentials: fetchCredentialsForPath(url),
         signal
       });
       return { response, ok: response.ok, status: response.status };
@@ -748,7 +752,7 @@ var HttpClient = class {
     }
     return fetch(`${this.config.baseUrl}${url}`, {
       ...init,
-      credentials: "include",
+      credentials: fetchCredentialsForPath(url),
       headers: mergedHeaders
     });
   }
@@ -4810,6 +4814,12 @@ function escapeToExternalBrowser(currentUrl) {
 var OAuthAPI = class {
   constructor(http) {
     this.http = http;
+    /**
+     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
+     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
+     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
+     */
+    this.bootConsumePromise = null;
   }
   /**
    * 활성화된 OAuth 프로바이더 목록 조회
@@ -5104,10 +5114,58 @@ var OAuthAPI = class {
       window.close();
       return result;
     }
+    if (this.bootConsumePromise) {
+      const consumed = await this.bootConsumePromise;
+      if (consumed) {
+        return result;
+      }
+    }
     this.http.setTokens(accessToken, refreshToken);
     await this.http.bootstrapRefreshCookie();
     return result;
   }
+  /**
+   * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
+   *
+   * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
+   * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
+   * 적재해 세션을 확립한다.
+   *
+   * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
+   * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
+   * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
+   * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
+   *
+   * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
+   * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
+   * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
+   * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
+   * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+   *
+   * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
+   */
+  consumeRedirectCallbackOnBoot() {
+    if (!this.bootConsumePromise) {
+      this.bootConsumePromise = this.doConsumeRedirectOnBoot();
+    }
+    return this.bootConsumePromise;
+  }
+  async doConsumeRedirectOnBoot() {
+    try {
+      if (typeof window === "undefined" || !window.location) return false;
+      const params = new URLSearchParams(window.location.search);
+      if (params.get("error")) return false;
+      const accessToken = params.get("access_token");
+      const refreshToken = params.get("refresh_token");
+      const memberId = params.get("member_id");
+      if (!accessToken || !refreshToken || !memberId) return false;
+      this.http.setTokens(accessToken, refreshToken);
+      await this.http.bootstrapRefreshCookie();
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /**
    * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
    *
@@ -10870,8 +10928,12 @@ var ConnectBase = class {
     this.support = new SupportAPI(this.http);
     this.auth._attachAnalytics(this.analytics);
     const shouldAutoRestore = config.autoRestoreSession ?? true;
-    if (shouldAutoRestore && typeof window !== "undefined" && !this.isOAuthCallbackUrl()) {
-      this.http.setBootRestorePromise(this.http.tryRestoreSessionFromCookie());
+    if (shouldAutoRestore && typeof window !== "undefined") {
+      if (this.isOAuthRedirectCallbackUrl()) {
+        this.http.setBootRestorePromise(this.oauth.consumeRedirectCallbackOnBoot());
+      } else if (!this.isOAuthCallbackUrl()) {
+        this.http.setBootRestorePromise(this.http.tryRestoreSessionFromCookie());
+      }
     }
   }
   /**
@@ -10879,7 +10941,7 @@ var ConnectBase = class {
    *
    * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
    * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-   * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+   * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
    */
   isOAuthCallbackUrl() {
     if (typeof window === "undefined" || !window.location) return false;
@@ -10889,6 +10951,20 @@ var ConnectBase = class {
     if (params.has("error") && params.has("state")) return true;
     return false;
   }
+  /**
+   * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
+   *
+   * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
+   * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
+   * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
+   * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
+   */
+  isOAuthRedirectCallbackUrl() {
+    if (typeof window === "undefined" || !window.location) return false;
+    if (window.opener) return false;
+    const params = new URLSearchParams(window.location.search);
+    return params.has("access_token") && params.has("refresh_token");
+  }
   /**
    * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
    *

package/dist/index.mjs

@@ -107,6 +107,10 @@ function sanitizePathForBreadcrumb(rawUrl) {
 }
 
 // src/core/http.ts
+function fetchCredentialsForPath(url) {
+  const path = url.split("?")[0];
+  return path.startsWith("/v1/public/") ? "omit" : "include";
+}
 var TOKEN_STORAGE_KEY = "cb_auth_tokens";
 function decodeJwtPayload(token) {
   try {
@@ -633,7 +637,7 @@ var HttpClient = class {
     try {
       const response = await fetch(`${this.config.baseUrl}${url}`, {
         ...init,
-        credentials: "include",
+        credentials: fetchCredentialsForPath(url),
         signal
       });
       return { response, ok: response.ok, status: response.status };
@@ -702,7 +706,7 @@ var HttpClient = class {
     }
     return fetch(`${this.config.baseUrl}${url}`, {
       ...init,
-      credentials: "include",
+      credentials: fetchCredentialsForPath(url),
       headers: mergedHeaders
     });
   }
@@ -4764,6 +4768,12 @@ function escapeToExternalBrowser(currentUrl) {
 var OAuthAPI = class {
   constructor(http) {
     this.http = http;
+    /**
+     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
+     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
+     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
+     */
+    this.bootConsumePromise = null;
   }
   /**
    * 활성화된 OAuth 프로바이더 목록 조회
@@ -5058,10 +5068,58 @@ var OAuthAPI = class {
       window.close();
       return result;
     }
+    if (this.bootConsumePromise) {
+      const consumed = await this.bootConsumePromise;
+      if (consumed) {
+        return result;
+      }
+    }
     this.http.setTokens(accessToken, refreshToken);
     await this.http.bootstrapRefreshCookie();
     return result;
   }
+  /**
+   * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
+   *
+   * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
+   * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
+   * 적재해 세션을 확립한다.
+   *
+   * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
+   * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
+   * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
+   * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
+   *
+   * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
+   * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
+   * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
+   * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
+   * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+   *
+   * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
+   */
+  consumeRedirectCallbackOnBoot() {
+    if (!this.bootConsumePromise) {
+      this.bootConsumePromise = this.doConsumeRedirectOnBoot();
+    }
+    return this.bootConsumePromise;
+  }
+  async doConsumeRedirectOnBoot() {
+    try {
+      if (typeof window === "undefined" || !window.location) return false;
+      const params = new URLSearchParams(window.location.search);
+      if (params.get("error")) return false;
+      const accessToken = params.get("access_token");
+      const refreshToken = params.get("refresh_token");
+      const memberId = params.get("member_id");
+      if (!accessToken || !refreshToken || !memberId) return false;
+      this.http.setTokens(accessToken, refreshToken);
+      await this.http.bootstrapRefreshCookie();
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /**
    * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
    *
@@ -10824,8 +10882,12 @@ var ConnectBase = class {
     this.support = new SupportAPI(this.http);
     this.auth._attachAnalytics(this.analytics);
     const shouldAutoRestore = config.autoRestoreSession ?? true;
-    if (shouldAutoRestore && typeof window !== "undefined" && !this.isOAuthCallbackUrl()) {
-      this.http.setBootRestorePromise(this.http.tryRestoreSessionFromCookie());
+    if (shouldAutoRestore && typeof window !== "undefined") {
+      if (this.isOAuthRedirectCallbackUrl()) {
+        this.http.setBootRestorePromise(this.oauth.consumeRedirectCallbackOnBoot());
+      } else if (!this.isOAuthCallbackUrl()) {
+        this.http.setBootRestorePromise(this.http.tryRestoreSessionFromCookie());
+      }
     }
   }
   /**
@@ -10833,7 +10895,7 @@ var ConnectBase = class {
    *
    * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
    * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-   * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+   * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
    */
   isOAuthCallbackUrl() {
     if (typeof window === "undefined" || !window.location) return false;
@@ -10843,6 +10905,20 @@ var ConnectBase = class {
     if (params.has("error") && params.has("state")) return true;
     return false;
   }
+  /**
+   * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
+   *
+   * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
+   * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
+   * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
+   * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
+   */
+  isOAuthRedirectCallbackUrl() {
+    if (typeof window === "undefined" || !window.location) return false;
+    if (window.opener) return false;
+    const params = new URLSearchParams(window.location.search);
+    return params.has("access_token") && params.has("refresh_token");
+  }
   /**
    * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
    *

package/package.json

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