connectbase-client 3.3.1 → 3.5.0

package/dist/index.d.mts

@@ -314,6 +314,18 @@ declare class SessionManager {
     touch(): void;
     /** 세션 강제 리셋 */
     reset(): void;
+    /**
+     * visitor_uid 를 새로 발급하고 세션도 함께 초기화.
+     *
+     * 사용 시점:
+     * - 사용자 로그아웃 (이전 사용자 활동이 다음 사용자에 attribution 되는 것 방지)
+     * - 다른 사용자 로그인 감지 (link-member 가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답)
+     *
+     * localStorage 의 `__cb_visitor_uid` 가 새 UUID 로 교체되며 sessionStorage 의
+     * 세션 키도 같이 비워진다. 이후의 모든 batch 는 새 visitor 로 기록되어 멤버 간
+     * 데이터 오염이 차단된다.
+     */
+    regenerateVisitorUid(): string;
     private ensureSession;
     private loadOrCreateVisitorUid;
 }
@@ -368,6 +380,11 @@ declare class AnalyticsAPI {
      * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
      * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
      *
+     * **사용자 전환 자동 처리 (1.13.0+)**: 동일 브라우저에서 다른 사용자가 로그인해
+     * 백엔드가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 보내면, 큐를 비우고
+     * `visitor_uid` 를 새로 발급한 뒤 link-member 를 한 번 더 호출해 새 visitor 가
+     * 즉시 회원으로 기록되도록 자가 복구한다.
+     *
      * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
      *
      * @example
@@ -378,11 +395,30 @@ declare class AnalyticsAPI {
      * ```
      */
     identify(memberId: string): void;
+    /**
+     * 로그아웃 / 사용자 전환 시 호출. 익명 상태로 복귀하면서 visitor_uid 를 새로
+     * 발급해 다음 사용자의 활동이 이전 사용자에게 attribution 되는 데이터 오염을 차단.
+     *
+     * 동작:
+     * 1. memberId 를 null 로 설정 (이후 batch 는 익명으로 기록)
+     * 2. 큐에 쌓인 미전송 이벤트 폐기 (이전 visitor 로 가는 것을 막기 위함)
+     * 3. localStorage `__cb_visitor_uid` 새 UUID 로 교체 + sessionStorage 세션 키 정리
+     * 4. heatmap 큐도 함께 비움
+     *
+     * @example
+     * ```ts
+     * // 로그아웃 핸들러
+     * await cb.auth.signOut()
+     * cb.analytics.reset()
+     * ```
+     */
+    reset(): void;
     /**
      * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
      *
      * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
-     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
+     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃 시에는
+     * 데이터 오염 방지를 위해 `reset()` 를 권장).
      */
     setMemberId(memberId: string | null): void;
     /**
@@ -390,6 +426,9 @@ declare class AnalyticsAPI {
      *
      * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
      *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+     * - 다른 멤버에 이미 연결된 visitor 인 경우 (`VISITOR_LINKED_TO_OTHER_MEMBER`)
+     *   visitor_uid 를 자동 재발급하고 link-member 를 한 번 더 호출 — 한 단계의 자가
+     *   복구로 끝나며 무한 재귀를 막기 위해 두 번째 시도는 응답을 더 보지 않는다.
      * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
      */
     private linkMemberSilent;
@@ -510,7 +549,13 @@ declare class AnalyticsAPI {
     private createBaseEvent;
     private enqueue;
     private flushQueue;
-    /** sendBeacon으로 동기 flush (beforeunload용) */
+    /**
+     * sendBeacon 으로 동기 flush (beforeunload 용).
+     *
+     * sendBeacon 은 일반 fetch 와 달리 User-Agent 헤더가 신뢰할 수 있지만, 백엔드 봇
+     * 탐지가 body 의 `user_agent` 필드 첫 번째 값만 보므로 여기서도 동일하게 채워
+     * 첫 방문이 unload 타이밍에 도달했을 때 봇으로 오판되는 것을 방지한다.
+     */
     private flushSync;
     private trackSessionStart;
     private startBatchTimer;
@@ -6507,9 +6552,21 @@ interface ListDocumentsResponse {
     documents: DocumentResponse[];
     total_count: number;
 }
+/**
+ * 사용자 격리용 magic 토큰. `where` 값에 이 문자열을 넣으면 서버가
+ * 인증된 AppMember ID 로 자동 치환한다 (클라이언트 변조 불가).
+ *
+ * AppMember JWT 가 함께 오지 않은 호출에서 사용하면 401.
+ */
+declare const AUTH_MEMBER_ID_TOKEN: "$auth.member_id";
 /**
  * 검색 요청
  * @example { query: "환불 방법", top_k: 5, agentic: true }
+ *
+ * 사용자별 격리 (AppMember JWT 가 Authorization 헤더로 함께 올 때):
+ * - 서버가 자동으로 본인 metadata.user_id 문서로 결과를 제한.
+ * - `where` 로 추가 필터를 걸 수 있음. magic 토큰 사용 예:
+ *   `where: { 'metadata.tag': 'work' }`
  */
 interface KnowledgeSearchRequest {
     /** 검색 쿼리 (필수) */
@@ -6518,6 +6575,12 @@ interface KnowledgeSearchRequest {
     top_k?: number;
     /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
     agentic?: boolean;
+    /**
+     * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
+     * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
+     * AppMember JWT 컨텍스트가 있으면 서버가 추가로 metadata.user_id 강제 필터를 AND.
+     */
+    where?: Record<string, unknown>;
 }
 interface KnowledgeSearchResult {
     chunk_id: string;
@@ -6541,6 +6604,13 @@ interface KnowledgeSearchResponse {
  * AI 데이터베이스를 위한 문서 저장 및 검색 API.
  * 문서를 업로드하면 자동으로 청킹되어 키워드 기반 검색이 가능합니다.
  *
+ * ## 사용자별 격리 (다중 사용자 RAG 시나리오)
+ *
+ * `Authorization: Bearer <appmember-jwt>` 를 함께 보내면 서버가:
+ * - 검색 결과를 본인 문서 (metadata.user_id == member_id) 로 제한
+ * - addDocument 시 metadata.user_id 자동 태깅
+ * - listDocuments / deleteDocument 도 본인 자료만 노출
+ *
  * @example
  * ```typescript
  * const cb = new ConnectBase({ publicKey: 'your-public-key' })
@@ -6557,6 +6627,12 @@ interface KnowledgeSearchResponse {
  *     query: '환불 정책',
  *     top_k: 5
  * })
+ *
+ * // 사용자별 격리 + 추가 필터 (AppMember JWT 가 같이 와야 함)
+ * const results = await cb.knowledge.search('kb-id', {
+ *     query: '내 메모',
+ *     where: { 'metadata.tag': 'work' },
+ * })
  * ```
  */
 declare class KnowledgeAPI {
@@ -7445,4 +7521,4 @@ declare class ConnectBase {
     updateConfig(config: Partial<ConnectBaseConfig>): void;
 }
 
-export { AIAPI, type AIChatRequest, type AIChatResponse, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchSetPageMetaRequest, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type Channel, type ChannelMembership, type ChargeWithBillingKeyRequest, type ChargeWithBillingKeyResponse, type ChatMessage, type ClientMessage, type ColumnSchema, type CommentListResponse, type CompleteUploadRequest, type CompleteUploadResponse, type ConfirmBillingKeyRequest, type ConfirmPaymentRequest, type ConfirmPaymentResponse, ConnectBase, type ConnectBaseConfig, type ConnectedData, type ConnectionState, type ConsentOptions, type ConsumeMessagesResponse, type ConsumeOptions, type CopyTableRequest, type CopyTableResponse, type CreateBackupRequest, type CreateChannelRequest, type CreateCheckoutSessionRequest, type CreateCheckoutSessionResponse, type CreateColumnRequest, type CreateDataRequest, type CreateDocumentRequest, type CreateFolderRequest, type CreateFolderResponse, type CreateGeoIndexRequest, type CreateIndexRequest, type CreateLobbyRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateSearchIndexRequest, type CreateSecurityRuleRequest, type CreateSubscriptionRequest, type CreateTableRequest, type CreateTriggerRequest, type CreateVideoStorageRequest, type DailyReport, type DataItem, type DataType, type DatabaseChange, type DatabaseChangeMessage, type DatabaseChangeType, type DatabaseRealtimeConnectOptions, type DatabaseRealtimeFilter, type DatabaseRealtimeHandlers, type DatabaseRealtimeSubscription, type DatabaseSnapshot, type DatabaseSnapshotMessage, type DatabaseSubscribeOptions, type DeleteWhereResponse, type DeviceInfo, type DocumentResponse, type EnabledProviderInfo, type EnabledProvidersResponse, EndpointAPI, type EndpointCallInit, type ErrorHandler, type ErrorMessage, type ErrorReport, type ErrorTrackerConfig, type ErrorType, type ExportDataRequest, type ExportDataResponse, type FetchDataResponse, type FetchFilesResponse, type FetchPublicKeysResponse, type FileItem, type FileStats, GameAPI, type GameAction, type GameClientConfig, type GameConfig, GameConfigAPI, type GameConfigPatch, type GameConnectionState, type GameConnectionStatus, type GameDelta, type GameEventHandlers, type GamePlayer, GameRoom, type GameRoomConfig, type GameRoomInfo, GameRoomTransport, type GameServerMessage, type GameServerMessageType, type GameState, type GameTransportConfig, type GenerateUploadURLByPathRequest, type GenerateUploadURLRequest, type GenerateUploadURLResponse, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GeoWithin, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, type GuestMemberSignInResponse, type HistoryResponse, type ICEServer, type ICEServersResponse, type ImageResult, type ImportDataRequest, type ImportDataResponse, type IndexAnalysis, type IndexRecommendation, type InitUploadResponse, type InvokeFunctionRequest, type InvokeFunctionResponse, type IssueBillingKeyRequest, type IssueBillingKeyResponse, type JoinQueueRequest, type JoinRoomRequest, type JoinRoomResponse, type KnowledgeSearchRequest, type KnowledgeSearchResponse, type KnowledgeSearchResult, type LeaderboardEntry, type LeaderboardListResponse, type LeaderboardScoreEntry, type LifecyclePolicy, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListSubscriptionPaymentsRequest, type ListSubscriptionPaymentsResponse, type ListSubscriptionsRequest, type ListSubscriptionsResponse, type LobbyInfo, type LobbyInvite, type LobbyMember, type LobbyVisibility, type MatchResult, type MatchmakingTicket, type MatchqueueListResponse, type MatchqueueTicket, type MemberInfoResponse, type MemberSignInRequest, type MemberSignInResponse, type MemberSignUpRequest, type MemberSignUpResponse, type MembershipTier, type MemoryInfo, type MessageHandler, type MigrateDataRequest, type MigrateDataResponse, type MoveFileRequest, type NackMessageRequest, NativeAPI, type OAuthCallbackResponse, type OAuthProvider, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentProvider, type PaymentStatus, type PeerInfo, type Platform, type PlayerEvent, type PlayerStats, type Playlist, type PlaylistItem, type PollUntilOptions, type PongMessage, type PopulateOption, type Position, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type PublicKeyItem, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoomInfo, type RoomStats, type RoomsResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptMeta, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamMessage, type StreamOptions, type StreamSession, type StreamTokenCallback, type StreamToolCallCallback, type StreamToolResultCallback, type StreamURLResponse, type SubscribeOptions, type SubscribeTopicRequest, type SubscribedData, type Subscription, type SubscriptionPaymentResponse, type SubscriptionPaymentStatus, type SubscriptionResponse, type SubscriptionStatus, type SuperChat, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionWrite, type TranscodeStatus, type TransportType, type Trigger, type TriggerEvent, type TriggerHandlerType, type TypingChangeHandler, type TypingInfo, type UpdateBillingKeyRequest, type UpdateChannelRequest, type UpdateColumnRequest, type UpdateCustomDataRequest, type UpdateCustomDataResponse, type UpdateDataRequest, type UpdateLobbyRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageListResponse, type VideoVisibility, type VoiceChannel, type VoiceMember, type WaitOptions, type WatchHistoryItem, type WebPushSubscription, type WebRTCConnectOptions, type WebRTCConnectionState, type WebRTCMode, type WhereCondition, type WhereOperator, ConnectBase as default, isWebTransportSupported };
+export { AIAPI, type AIChatRequest, type AIChatResponse, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchSetPageMetaRequest, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type Channel, type ChannelMembership, type ChargeWithBillingKeyRequest, type ChargeWithBillingKeyResponse, type ChatMessage, type ClientMessage, type ColumnSchema, type CommentListResponse, type CompleteUploadRequest, type CompleteUploadResponse, type ConfirmBillingKeyRequest, type ConfirmPaymentRequest, type ConfirmPaymentResponse, ConnectBase, type ConnectBaseConfig, type ConnectedData, type ConnectionState, type ConsentOptions, type ConsumeMessagesResponse, type ConsumeOptions, type CopyTableRequest, type CopyTableResponse, type CreateBackupRequest, type CreateChannelRequest, type CreateCheckoutSessionRequest, type CreateCheckoutSessionResponse, type CreateColumnRequest, type CreateDataRequest, type CreateDocumentRequest, type CreateFolderRequest, type CreateFolderResponse, type CreateGeoIndexRequest, type CreateIndexRequest, type CreateLobbyRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateSearchIndexRequest, type CreateSecurityRuleRequest, type CreateSubscriptionRequest, type CreateTableRequest, type CreateTriggerRequest, type CreateVideoStorageRequest, type DailyReport, type DataItem, type DataType, type DatabaseChange, type DatabaseChangeMessage, type DatabaseChangeType, type DatabaseRealtimeConnectOptions, type DatabaseRealtimeFilter, type DatabaseRealtimeHandlers, type DatabaseRealtimeSubscription, type DatabaseSnapshot, type DatabaseSnapshotMessage, type DatabaseSubscribeOptions, type DeleteWhereResponse, type DeviceInfo, type DocumentResponse, type EnabledProviderInfo, type EnabledProvidersResponse, EndpointAPI, type EndpointCallInit, type ErrorHandler, type ErrorMessage, type ErrorReport, type ErrorTrackerConfig, type ErrorType, type ExportDataRequest, type ExportDataResponse, type FetchDataResponse, type FetchFilesResponse, type FetchPublicKeysResponse, type FileItem, type FileStats, GameAPI, type GameAction, type GameClientConfig, type GameConfig, GameConfigAPI, type GameConfigPatch, type GameConnectionState, type GameConnectionStatus, type GameDelta, type GameEventHandlers, type GamePlayer, GameRoom, type GameRoomConfig, type GameRoomInfo, GameRoomTransport, type GameServerMessage, type GameServerMessageType, type GameState, type GameTransportConfig, type GenerateUploadURLByPathRequest, type GenerateUploadURLRequest, type GenerateUploadURLResponse, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GeoWithin, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, type GuestMemberSignInResponse, type HistoryResponse, type ICEServer, type ICEServersResponse, type ImageResult, type ImportDataRequest, type ImportDataResponse, type IndexAnalysis, type IndexRecommendation, type InitUploadResponse, type InvokeFunctionRequest, type InvokeFunctionResponse, type IssueBillingKeyRequest, type IssueBillingKeyResponse, type JoinQueueRequest, type JoinRoomRequest, type JoinRoomResponse, type KnowledgeSearchRequest, type KnowledgeSearchResponse, type KnowledgeSearchResult, type LeaderboardEntry, type LeaderboardListResponse, type LeaderboardScoreEntry, type LifecyclePolicy, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListSubscriptionPaymentsRequest, type ListSubscriptionPaymentsResponse, type ListSubscriptionsRequest, type ListSubscriptionsResponse, type LobbyInfo, type LobbyInvite, type LobbyMember, type LobbyVisibility, type MatchResult, type MatchmakingTicket, type MatchqueueListResponse, type MatchqueueTicket, type MemberInfoResponse, type MemberSignInRequest, type MemberSignInResponse, type MemberSignUpRequest, type MemberSignUpResponse, type MembershipTier, type MemoryInfo, type MessageHandler, type MigrateDataRequest, type MigrateDataResponse, type MoveFileRequest, type NackMessageRequest, NativeAPI, type OAuthCallbackResponse, type OAuthProvider, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentProvider, type PaymentStatus, type PeerInfo, type Platform, type PlayerEvent, type PlayerStats, type Playlist, type PlaylistItem, type PollUntilOptions, type PongMessage, type PopulateOption, type Position, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type PublicKeyItem, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoomInfo, type RoomStats, type RoomsResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptMeta, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamMessage, type StreamOptions, type StreamSession, type StreamTokenCallback, type StreamToolCallCallback, type StreamToolResultCallback, type StreamURLResponse, type SubscribeOptions, type SubscribeTopicRequest, type SubscribedData, type Subscription, type SubscriptionPaymentResponse, type SubscriptionPaymentStatus, type SubscriptionResponse, type SubscriptionStatus, type SuperChat, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionWrite, type TranscodeStatus, type TransportType, type Trigger, type TriggerEvent, type TriggerHandlerType, type TypingChangeHandler, type TypingInfo, type UpdateBillingKeyRequest, type UpdateChannelRequest, type UpdateColumnRequest, type UpdateCustomDataRequest, type UpdateCustomDataResponse, type UpdateDataRequest, type UpdateLobbyRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageListResponse, type VideoVisibility, type VoiceChannel, type VoiceMember, type WaitOptions, type WatchHistoryItem, type WebPushSubscription, type WebRTCConnectOptions, type WebRTCConnectionState, type WebRTCMode, type WhereCondition, type WhereOperator, ConnectBase as default, isWebTransportSupported };

package/dist/index.d.ts

@@ -314,6 +314,18 @@ declare class SessionManager {
     touch(): void;
     /** 세션 강제 리셋 */
     reset(): void;
+    /**
+     * visitor_uid 를 새로 발급하고 세션도 함께 초기화.
+     *
+     * 사용 시점:
+     * - 사용자 로그아웃 (이전 사용자 활동이 다음 사용자에 attribution 되는 것 방지)
+     * - 다른 사용자 로그인 감지 (link-member 가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답)
+     *
+     * localStorage 의 `__cb_visitor_uid` 가 새 UUID 로 교체되며 sessionStorage 의
+     * 세션 키도 같이 비워진다. 이후의 모든 batch 는 새 visitor 로 기록되어 멤버 간
+     * 데이터 오염이 차단된다.
+     */
+    regenerateVisitorUid(): string;
     private ensureSession;
     private loadOrCreateVisitorUid;
 }
@@ -368,6 +380,11 @@ declare class AnalyticsAPI {
      * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
      * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
      *
+     * **사용자 전환 자동 처리 (1.13.0+)**: 동일 브라우저에서 다른 사용자가 로그인해
+     * 백엔드가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 보내면, 큐를 비우고
+     * `visitor_uid` 를 새로 발급한 뒤 link-member 를 한 번 더 호출해 새 visitor 가
+     * 즉시 회원으로 기록되도록 자가 복구한다.
+     *
      * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
      *
      * @example
@@ -378,11 +395,30 @@ declare class AnalyticsAPI {
      * ```
      */
     identify(memberId: string): void;
+    /**
+     * 로그아웃 / 사용자 전환 시 호출. 익명 상태로 복귀하면서 visitor_uid 를 새로
+     * 발급해 다음 사용자의 활동이 이전 사용자에게 attribution 되는 데이터 오염을 차단.
+     *
+     * 동작:
+     * 1. memberId 를 null 로 설정 (이후 batch 는 익명으로 기록)
+     * 2. 큐에 쌓인 미전송 이벤트 폐기 (이전 visitor 로 가는 것을 막기 위함)
+     * 3. localStorage `__cb_visitor_uid` 새 UUID 로 교체 + sessionStorage 세션 키 정리
+     * 4. heatmap 큐도 함께 비움
+     *
+     * @example
+     * ```ts
+     * // 로그아웃 핸들러
+     * await cb.auth.signOut()
+     * cb.analytics.reset()
+     * ```
+     */
+    reset(): void;
     /**
      * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
      *
      * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
-     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
+     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃 시에는
+     * 데이터 오염 방지를 위해 `reset()` 를 권장).
      */
     setMemberId(memberId: string | null): void;
     /**
@@ -390,6 +426,9 @@ declare class AnalyticsAPI {
      *
      * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
      *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+     * - 다른 멤버에 이미 연결된 visitor 인 경우 (`VISITOR_LINKED_TO_OTHER_MEMBER`)
+     *   visitor_uid 를 자동 재발급하고 link-member 를 한 번 더 호출 — 한 단계의 자가
+     *   복구로 끝나며 무한 재귀를 막기 위해 두 번째 시도는 응답을 더 보지 않는다.
      * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
      */
     private linkMemberSilent;
@@ -510,7 +549,13 @@ declare class AnalyticsAPI {
     private createBaseEvent;
     private enqueue;
     private flushQueue;
-    /** sendBeacon으로 동기 flush (beforeunload용) */
+    /**
+     * sendBeacon 으로 동기 flush (beforeunload 용).
+     *
+     * sendBeacon 은 일반 fetch 와 달리 User-Agent 헤더가 신뢰할 수 있지만, 백엔드 봇
+     * 탐지가 body 의 `user_agent` 필드 첫 번째 값만 보므로 여기서도 동일하게 채워
+     * 첫 방문이 unload 타이밍에 도달했을 때 봇으로 오판되는 것을 방지한다.
+     */
     private flushSync;
     private trackSessionStart;
     private startBatchTimer;
@@ -6507,9 +6552,21 @@ interface ListDocumentsResponse {
     documents: DocumentResponse[];
     total_count: number;
 }
+/**
+ * 사용자 격리용 magic 토큰. `where` 값에 이 문자열을 넣으면 서버가
+ * 인증된 AppMember ID 로 자동 치환한다 (클라이언트 변조 불가).
+ *
+ * AppMember JWT 가 함께 오지 않은 호출에서 사용하면 401.
+ */
+declare const AUTH_MEMBER_ID_TOKEN: "$auth.member_id";
 /**
  * 검색 요청
  * @example { query: "환불 방법", top_k: 5, agentic: true }
+ *
+ * 사용자별 격리 (AppMember JWT 가 Authorization 헤더로 함께 올 때):
+ * - 서버가 자동으로 본인 metadata.user_id 문서로 결과를 제한.
+ * - `where` 로 추가 필터를 걸 수 있음. magic 토큰 사용 예:
+ *   `where: { 'metadata.tag': 'work' }`
  */
 interface KnowledgeSearchRequest {
     /** 검색 쿼리 (필수) */
@@ -6518,6 +6575,12 @@ interface KnowledgeSearchRequest {
     top_k?: number;
     /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
     agentic?: boolean;
+    /**
+     * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
+     * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
+     * AppMember JWT 컨텍스트가 있으면 서버가 추가로 metadata.user_id 강제 필터를 AND.
+     */
+    where?: Record<string, unknown>;
 }
 interface KnowledgeSearchResult {
     chunk_id: string;
@@ -6541,6 +6604,13 @@ interface KnowledgeSearchResponse {
  * AI 데이터베이스를 위한 문서 저장 및 검색 API.
  * 문서를 업로드하면 자동으로 청킹되어 키워드 기반 검색이 가능합니다.
  *
+ * ## 사용자별 격리 (다중 사용자 RAG 시나리오)
+ *
+ * `Authorization: Bearer <appmember-jwt>` 를 함께 보내면 서버가:
+ * - 검색 결과를 본인 문서 (metadata.user_id == member_id) 로 제한
+ * - addDocument 시 metadata.user_id 자동 태깅
+ * - listDocuments / deleteDocument 도 본인 자료만 노출
+ *
  * @example
  * ```typescript
  * const cb = new ConnectBase({ publicKey: 'your-public-key' })
@@ -6557,6 +6627,12 @@ interface KnowledgeSearchResponse {
  *     query: '환불 정책',
  *     top_k: 5
  * })
+ *
+ * // 사용자별 격리 + 추가 필터 (AppMember JWT 가 같이 와야 함)
+ * const results = await cb.knowledge.search('kb-id', {
+ *     query: '내 메모',
+ *     where: { 'metadata.tag': 'work' },
+ * })
  * ```
  */
 declare class KnowledgeAPI {
@@ -7445,4 +7521,4 @@ declare class ConnectBase {
     updateConfig(config: Partial<ConnectBaseConfig>): void;
 }
 
-export { AIAPI, type AIChatRequest, type AIChatResponse, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchSetPageMetaRequest, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type Channel, type ChannelMembership, type ChargeWithBillingKeyRequest, type ChargeWithBillingKeyResponse, type ChatMessage, type ClientMessage, type ColumnSchema, type CommentListResponse, type CompleteUploadRequest, type CompleteUploadResponse, type ConfirmBillingKeyRequest, type ConfirmPaymentRequest, type ConfirmPaymentResponse, ConnectBase, type ConnectBaseConfig, type ConnectedData, type ConnectionState, type ConsentOptions, type ConsumeMessagesResponse, type ConsumeOptions, type CopyTableRequest, type CopyTableResponse, type CreateBackupRequest, type CreateChannelRequest, type CreateCheckoutSessionRequest, type CreateCheckoutSessionResponse, type CreateColumnRequest, type CreateDataRequest, type CreateDocumentRequest, type CreateFolderRequest, type CreateFolderResponse, type CreateGeoIndexRequest, type CreateIndexRequest, type CreateLobbyRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateSearchIndexRequest, type CreateSecurityRuleRequest, type CreateSubscriptionRequest, type CreateTableRequest, type CreateTriggerRequest, type CreateVideoStorageRequest, type DailyReport, type DataItem, type DataType, type DatabaseChange, type DatabaseChangeMessage, type DatabaseChangeType, type DatabaseRealtimeConnectOptions, type DatabaseRealtimeFilter, type DatabaseRealtimeHandlers, type DatabaseRealtimeSubscription, type DatabaseSnapshot, type DatabaseSnapshotMessage, type DatabaseSubscribeOptions, type DeleteWhereResponse, type DeviceInfo, type DocumentResponse, type EnabledProviderInfo, type EnabledProvidersResponse, EndpointAPI, type EndpointCallInit, type ErrorHandler, type ErrorMessage, type ErrorReport, type ErrorTrackerConfig, type ErrorType, type ExportDataRequest, type ExportDataResponse, type FetchDataResponse, type FetchFilesResponse, type FetchPublicKeysResponse, type FileItem, type FileStats, GameAPI, type GameAction, type GameClientConfig, type GameConfig, GameConfigAPI, type GameConfigPatch, type GameConnectionState, type GameConnectionStatus, type GameDelta, type GameEventHandlers, type GamePlayer, GameRoom, type GameRoomConfig, type GameRoomInfo, GameRoomTransport, type GameServerMessage, type GameServerMessageType, type GameState, type GameTransportConfig, type GenerateUploadURLByPathRequest, type GenerateUploadURLRequest, type GenerateUploadURLResponse, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GeoWithin, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, type GuestMemberSignInResponse, type HistoryResponse, type ICEServer, type ICEServersResponse, type ImageResult, type ImportDataRequest, type ImportDataResponse, type IndexAnalysis, type IndexRecommendation, type InitUploadResponse, type InvokeFunctionRequest, type InvokeFunctionResponse, type IssueBillingKeyRequest, type IssueBillingKeyResponse, type JoinQueueRequest, type JoinRoomRequest, type JoinRoomResponse, type KnowledgeSearchRequest, type KnowledgeSearchResponse, type KnowledgeSearchResult, type LeaderboardEntry, type LeaderboardListResponse, type LeaderboardScoreEntry, type LifecyclePolicy, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListSubscriptionPaymentsRequest, type ListSubscriptionPaymentsResponse, type ListSubscriptionsRequest, type ListSubscriptionsResponse, type LobbyInfo, type LobbyInvite, type LobbyMember, type LobbyVisibility, type MatchResult, type MatchmakingTicket, type MatchqueueListResponse, type MatchqueueTicket, type MemberInfoResponse, type MemberSignInRequest, type MemberSignInResponse, type MemberSignUpRequest, type MemberSignUpResponse, type MembershipTier, type MemoryInfo, type MessageHandler, type MigrateDataRequest, type MigrateDataResponse, type MoveFileRequest, type NackMessageRequest, NativeAPI, type OAuthCallbackResponse, type OAuthProvider, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentProvider, type PaymentStatus, type PeerInfo, type Platform, type PlayerEvent, type PlayerStats, type Playlist, type PlaylistItem, type PollUntilOptions, type PongMessage, type PopulateOption, type Position, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type PublicKeyItem, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoomInfo, type RoomStats, type RoomsResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptMeta, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamMessage, type StreamOptions, type StreamSession, type StreamTokenCallback, type StreamToolCallCallback, type StreamToolResultCallback, type StreamURLResponse, type SubscribeOptions, type SubscribeTopicRequest, type SubscribedData, type Subscription, type SubscriptionPaymentResponse, type SubscriptionPaymentStatus, type SubscriptionResponse, type SubscriptionStatus, type SuperChat, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionWrite, type TranscodeStatus, type TransportType, type Trigger, type TriggerEvent, type TriggerHandlerType, type TypingChangeHandler, type TypingInfo, type UpdateBillingKeyRequest, type UpdateChannelRequest, type UpdateColumnRequest, type UpdateCustomDataRequest, type UpdateCustomDataResponse, type UpdateDataRequest, type UpdateLobbyRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageListResponse, type VideoVisibility, type VoiceChannel, type VoiceMember, type WaitOptions, type WatchHistoryItem, type WebPushSubscription, type WebRTCConnectOptions, type WebRTCConnectionState, type WebRTCMode, type WhereCondition, type WhereOperator, ConnectBase as default, isWebTransportSupported };
+export { AIAPI, type AIChatRequest, type AIChatResponse, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchSetPageMetaRequest, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type Channel, type ChannelMembership, type ChargeWithBillingKeyRequest, type ChargeWithBillingKeyResponse, type ChatMessage, type ClientMessage, type ColumnSchema, type CommentListResponse, type CompleteUploadRequest, type CompleteUploadResponse, type ConfirmBillingKeyRequest, type ConfirmPaymentRequest, type ConfirmPaymentResponse, ConnectBase, type ConnectBaseConfig, type ConnectedData, type ConnectionState, type ConsentOptions, type ConsumeMessagesResponse, type ConsumeOptions, type CopyTableRequest, type CopyTableResponse, type CreateBackupRequest, type CreateChannelRequest, type CreateCheckoutSessionRequest, type CreateCheckoutSessionResponse, type CreateColumnRequest, type CreateDataRequest, type CreateDocumentRequest, type CreateFolderRequest, type CreateFolderResponse, type CreateGeoIndexRequest, type CreateIndexRequest, type CreateLobbyRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateSearchIndexRequest, type CreateSecurityRuleRequest, type CreateSubscriptionRequest, type CreateTableRequest, type CreateTriggerRequest, type CreateVideoStorageRequest, type DailyReport, type DataItem, type DataType, type DatabaseChange, type DatabaseChangeMessage, type DatabaseChangeType, type DatabaseRealtimeConnectOptions, type DatabaseRealtimeFilter, type DatabaseRealtimeHandlers, type DatabaseRealtimeSubscription, type DatabaseSnapshot, type DatabaseSnapshotMessage, type DatabaseSubscribeOptions, type DeleteWhereResponse, type DeviceInfo, type DocumentResponse, type EnabledProviderInfo, type EnabledProvidersResponse, EndpointAPI, type EndpointCallInit, type ErrorHandler, type ErrorMessage, type ErrorReport, type ErrorTrackerConfig, type ErrorType, type ExportDataRequest, type ExportDataResponse, type FetchDataResponse, type FetchFilesResponse, type FetchPublicKeysResponse, type FileItem, type FileStats, GameAPI, type GameAction, type GameClientConfig, type GameConfig, GameConfigAPI, type GameConfigPatch, type GameConnectionState, type GameConnectionStatus, type GameDelta, type GameEventHandlers, type GamePlayer, GameRoom, type GameRoomConfig, type GameRoomInfo, GameRoomTransport, type GameServerMessage, type GameServerMessageType, type GameState, type GameTransportConfig, type GenerateUploadURLByPathRequest, type GenerateUploadURLRequest, type GenerateUploadURLResponse, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GeoWithin, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, type GuestMemberSignInResponse, type HistoryResponse, type ICEServer, type ICEServersResponse, type ImageResult, type ImportDataRequest, type ImportDataResponse, type IndexAnalysis, type IndexRecommendation, type InitUploadResponse, type InvokeFunctionRequest, type InvokeFunctionResponse, type IssueBillingKeyRequest, type IssueBillingKeyResponse, type JoinQueueRequest, type JoinRoomRequest, type JoinRoomResponse, type KnowledgeSearchRequest, type KnowledgeSearchResponse, type KnowledgeSearchResult, type LeaderboardEntry, type LeaderboardListResponse, type LeaderboardScoreEntry, type LifecyclePolicy, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListSubscriptionPaymentsRequest, type ListSubscriptionPaymentsResponse, type ListSubscriptionsRequest, type ListSubscriptionsResponse, type LobbyInfo, type LobbyInvite, type LobbyMember, type LobbyVisibility, type MatchResult, type MatchmakingTicket, type MatchqueueListResponse, type MatchqueueTicket, type MemberInfoResponse, type MemberSignInRequest, type MemberSignInResponse, type MemberSignUpRequest, type MemberSignUpResponse, type MembershipTier, type MemoryInfo, type MessageHandler, type MigrateDataRequest, type MigrateDataResponse, type MoveFileRequest, type NackMessageRequest, NativeAPI, type OAuthCallbackResponse, type OAuthProvider, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentProvider, type PaymentStatus, type PeerInfo, type Platform, type PlayerEvent, type PlayerStats, type Playlist, type PlaylistItem, type PollUntilOptions, type PongMessage, type PopulateOption, type Position, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type PublicKeyItem, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoomInfo, type RoomStats, type RoomsResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptMeta, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamMessage, type StreamOptions, type StreamSession, type StreamTokenCallback, type StreamToolCallCallback, type StreamToolResultCallback, type StreamURLResponse, type SubscribeOptions, type SubscribeTopicRequest, type SubscribedData, type Subscription, type SubscriptionPaymentResponse, type SubscriptionPaymentStatus, type SubscriptionResponse, type SubscriptionStatus, type SuperChat, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionWrite, type TranscodeStatus, type TransportType, type Trigger, type TriggerEvent, type TriggerHandlerType, type TypingChangeHandler, type TypingInfo, type UpdateBillingKeyRequest, type UpdateChannelRequest, type UpdateColumnRequest, type UpdateCustomDataRequest, type UpdateCustomDataResponse, type UpdateDataRequest, type UpdateLobbyRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageListResponse, type VideoVisibility, type VoiceChannel, type VoiceMember, type WaitOptions, type WatchHistoryItem, type WebPushSubscription, type WebRTCConnectOptions, type WebRTCConnectionState, type WebRTCMode, type WhereCondition, type WhereOperator, ConnectBase as default, isWebTransportSupported };

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AIAPI: () => AIAPI,
+  AUTH_MEMBER_ID_TOKEN: () => AUTH_MEMBER_ID_TOKEN,
   AdsAPI: () => AdsAPI,
   ApiError: () => ApiError,
   AuthError: () => AuthError,
@@ -8034,6 +8035,29 @@ var SessionManager = class {
     } catch {
     }
   }
+  /**
+   * visitor_uid 를 새로 발급하고 세션도 함께 초기화.
+   *
+   * 사용 시점:
+   * - 사용자 로그아웃 (이전 사용자 활동이 다음 사용자에 attribution 되는 것 방지)
+   * - 다른 사용자 로그인 감지 (link-member 가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답)
+   *
+   * localStorage 의 `__cb_visitor_uid` 가 새 UUID 로 교체되며 sessionStorage 의
+   * 세션 키도 같이 비워진다. 이후의 모든 batch 는 새 visitor 로 기록되어 멤버 간
+   * 데이터 오염이 차단된다.
+   */
+  regenerateVisitorUid() {
+    const newUid = generateId();
+    this._visitorUid = newUid;
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.setItem(VISITOR_KEY, newUid);
+      }
+    } catch {
+    }
+    this.reset();
+    return newUid;
+  }
   ensureSession() {
     const now = Date.now();
     if (!this._sessionId) {
@@ -8239,6 +8263,11 @@ var AnalyticsAPI = class {
    * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
    * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
    *
+   * **사용자 전환 자동 처리 (1.13.0+)**: 동일 브라우저에서 다른 사용자가 로그인해
+   * 백엔드가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 보내면, 큐를 비우고
+   * `visitor_uid` 를 새로 발급한 뒤 link-member 를 한 번 더 호출해 새 visitor 가
+   * 즉시 회원으로 기록되도록 자가 복구한다.
+   *
    * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
    *
    * @example
@@ -8249,14 +8278,42 @@ var AnalyticsAPI = class {
    * ```
    */
   identify(memberId) {
+    if (this.memberId && this.memberId !== memberId) {
+      this.reset();
+    }
     this.setMemberId(memberId);
     this.linkMemberSilent(memberId);
   }
+  /**
+   * 로그아웃 / 사용자 전환 시 호출. 익명 상태로 복귀하면서 visitor_uid 를 새로
+   * 발급해 다음 사용자의 활동이 이전 사용자에게 attribution 되는 데이터 오염을 차단.
+   *
+   * 동작:
+   * 1. memberId 를 null 로 설정 (이후 batch 는 익명으로 기록)
+   * 2. 큐에 쌓인 미전송 이벤트 폐기 (이전 visitor 로 가는 것을 막기 위함)
+   * 3. localStorage `__cb_visitor_uid` 새 UUID 로 교체 + sessionStorage 세션 키 정리
+   * 4. heatmap 큐도 함께 비움
+   *
+   * @example
+   * ```ts
+   * // 로그아웃 핸들러
+   * await cb.auth.signOut()
+   * cb.analytics.reset()
+   * ```
+   */
+  reset() {
+    this.setMemberId(null);
+    this.eventQueue = [];
+    this.heatmapQueue = [];
+    const newUid = this.session.regenerateVisitorUid();
+    this.log("Analytics reset", { newVisitorUid: newUid });
+  }
   /**
    * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
    *
    * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
-   * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
+   * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃 시에는
+   * 데이터 오염 방지를 위해 `reset()` 를 권장).
    */
   setMemberId(memberId) {
     this.memberId = memberId || null;
@@ -8278,9 +8335,12 @@ var AnalyticsAPI = class {
    *
    * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
    *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+   * - 다른 멤버에 이미 연결된 visitor 인 경우 (`VISITOR_LINKED_TO_OTHER_MEMBER`)
+   *   visitor_uid 를 자동 재발급하고 link-member 를 한 번 더 호출 — 한 단계의 자가
+   *   복구로 끝나며 무한 재귀를 막기 위해 두 번째 시도는 응답을 더 보지 않는다.
    * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
    */
-  linkMemberSilent(memberId) {
+  linkMemberSilent(memberId, isRetry = false) {
     if (!this.storageWebId) return;
     const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
     this.http.post(
@@ -8289,7 +8349,18 @@ var AnalyticsAPI = class {
         visitor_uid: this.session.visitorUid,
         app_member_id: memberId
       }
-    ).catch(() => {
+    ).then((resp) => {
+      if (!resp) return;
+      this.log("link-member response", resp);
+      if (!isRetry && resp.success === false && resp.code === "VISITOR_LINKED_TO_OTHER_MEMBER") {
+        this.log("user-switch detected \u2014 regenerating visitor_uid");
+        this.eventQueue = [];
+        this.heatmapQueue = [];
+        this.session.regenerateVisitorUid();
+        this.linkMemberSilent(memberId, true);
+      }
+    }).catch((err) => {
+      this.log("link-member silent fail", err);
     });
   }
   /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
@@ -8523,6 +8594,7 @@ var AnalyticsAPI = class {
   createBaseEvent(type) {
     return {
       type,
+      event_id: generateId(),
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       session_id: this.session.sessionId,
       visitor_uid: this.session.visitorUid
@@ -8545,6 +8617,7 @@ var AnalyticsAPI = class {
           visitor_uid: this.session.visitorUid,
           ...this.memberId ? { app_member_id: this.memberId } : {},
           events: events.map((e) => ({
+            event_id: e.event_id,
             timestamp: e.timestamp,
             page_path: e.page_path || "",
             page_url: e.page_url || "",
@@ -8574,7 +8647,13 @@ var AnalyticsAPI = class {
       this.log("Flush failed", err);
     }
   }
-  /** sendBeacon으로 동기 flush (beforeunload용) */
+  /**
+   * sendBeacon 으로 동기 flush (beforeunload 용).
+   *
+   * sendBeacon 은 일반 fetch 와 달리 User-Agent 헤더가 신뢰할 수 있지만, 백엔드 봇
+   * 탐지가 body 의 `user_agent` 필드 첫 번째 값만 보므로 여기서도 동일하게 채워
+   * 첫 방문이 unload 타이밍에 도달했을 때 봇으로 오판되는 것을 방지한다.
+   */
   flushSync() {
     if (this.eventQueue.length === 0 || !this.storageWebId) return;
     if (typeof navigator === "undefined" || !navigator.sendBeacon) return;
@@ -8582,20 +8661,30 @@ var AnalyticsAPI = class {
     const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
     const baseUrl = this.http.getBaseUrl();
     const url = `${baseUrl}${prefix}/storages/web/${this.storageWebId}/visitors/batch`;
+    const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
     const body = JSON.stringify({
       visitor_uid: this.session.visitorUid,
       ...this.memberId ? { app_member_id: this.memberId } : {},
       events: events.map((e) => ({
+        event_id: e.event_id,
         timestamp: e.timestamp,
         page_path: e.page_path || "",
         page_url: e.page_url || "",
         page_title: e.page_title || "",
         referrer: e.referrer || "",
+        user_agent: ua,
+        screen_width: e.screen_width || 0,
+        screen_height: e.screen_height || 0,
         session_id: e.session_id,
         session_start: e.type === "session_start",
         is_page_view: e.type === "page_view",
         event_name: e.event_name,
-        event_properties: e.event_properties
+        event_properties: e.event_properties,
+        utm_source: e.utm_source,
+        utm_medium: e.utm_medium,
+        utm_campaign: e.utm_campaign,
+        utm_content: e.utm_content,
+        utm_term: e.utm_term
       }))
     });
     try {
@@ -8767,6 +8856,9 @@ var AnalyticsAPI = class {
   }
 };
 
+// src/types/knowledge.ts
+var AUTH_MEMBER_ID_TOKEN = "$auth.member_id";
+
 // src/api/game-transport.ts
 var WebTransportTransport = class {
   constructor(config, onMessage, onClose, onError) {
@@ -9476,6 +9568,7 @@ var index_default = ConnectBase;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AIAPI,
+  AUTH_MEMBER_ID_TOKEN,
   AdsAPI,
   ApiError,
   AuthError,