connectbase-client 6.3.4 → 6.5.0

package/dist/index.d.mts

@@ -152,6 +152,64 @@ declare class GameError extends Error {
     /** `JSON.stringify(err)` 가 `{}` 가 되지 않도록 한다 (ApiError.toJSON 참조). */
     toJSON(): Record<string, unknown>;
 }
+/**
+ * 실시간(WebSocket) 연결 거부 코드. socket-server 가 연결을 받지 않은 이유이고, 대응이 코드마다 다르다.
+ *
+ * | 코드 | 원인 | 재시도 | 권장 대응 |
+ * |------|------|--------|-----------|
+ * | `connection_limit_exceeded` | 플랜의 동시접속 한도 도달 | 가능 | 다른 연결이 끊기면 자리가 난다. `details.current`/`details.limit` 확인, 계속되면 플랜 상향 |
+ * | `quota_exceeded` | 월간 WebSocket 사용 시간 소진 | 불가 | 플랜 업그레이드 전까지 재시도 무의미 |
+ * | `server_at_capacity` | 서버 일시 혼잡 | 가능 | 잠시 후 재시도 |
+ * | `auth_unavailable` | 인증 서버 일시 장애 | 가능 | 잠시 후 재시도 |
+ * | `unauthorized` | 공개 키/액세스 토큰이 유효하지 않음 | 불가 | 키·토큰 확인 (토큰 만료면 새 토큰으로 `connect()`) |
+ * | `forbidden` | 다른 앱의 경로로 접속 | 불가 | 설정 확인 |
+ * | `invalid_user_id` | 공개 키 연결에 UUID 형식 `userId` | 불가 | `accessToken` 을 쓰거나 UUID 가 아닌 식별자 사용 |
+ * | `internal_error` | 서버 설정 오류 | 가능 | 잠시 후 재시도 |
+ */
+type RealtimeConnectionErrorCode = "connection_limit_exceeded" | "quota_exceeded" | "server_at_capacity" | "auth_unavailable" | "unauthorized" | "forbidden" | "invalid_user_id" | "internal_error" | (string & {});
+/**
+ * 서버가 이유를 밝히고 실시간 연결을 거부했을 때 `cb.realtime.connect()` 가 던지는 에러.
+ *
+ * 브라우저의 WebSocket API 는 실패한 핸드셰이크의 HTTP 상태를 읽을 수 없어, 예전에는 동시접속
+ * 초과도 인증 실패도 "Connection timeout"/"Failed to connect" 로만 보였고 SDK 는 SSE 폴백으로
+ * 넘어가 subscribe/send 가 나중에야 이유 없이 실패했다(platform-issue 01a15d9d). 이제 서버가
+ * 연결을 받은 뒤 거부 이유를 보내고 4000+HTTP상태 close 코드(예: 4401, 4402, 4503)로 닫는다.
+ *
+ * - 거부는 SSE 폴백 대상이 아니다 — 네트워크는 정상이고 서버가 받지 않은 것이다.
+ * - 자동 재연결 중에 받은 거부는 `retryable` 이면 백오프로 계속 시도하고, 아니면 재연결을 멈추고
+ *   `cb.realtime.onError` 로 이 에러를 알린다.
+ *
+ * ```ts
+ * try {
+ *   await cb.realtime.connect()
+ * } catch (e) {
+ *   if (e instanceof RealtimeConnectionError) {
+ *     if (e.code === 'connection_limit_exceeded') showFull(e.details?.limit)
+ *     else if (e.retryable) setTimeout(() => cb.realtime.connect(), 5000)
+ *     else showConfigError(e.message)
+ *   }
+ * }
+ * ```
+ */
+declare class RealtimeConnectionError extends Error {
+    /** 문서화된 거부 코드. 분기 기준은 항상 이 필드다. */
+    code: RealtimeConnectionErrorCode;
+    /** WebSocket close 코드 (4000 + 서버의 HTTP 상태). */
+    closeCode: number;
+    /** 시간차를 두고 다시 연결하면 성공할 수 있는지. */
+    retryable: boolean;
+    /** 거부 상세 (예: connection_limit_exceeded 의 `current`/`limit`, quota_exceeded 의 `quota`/`unit`). */
+    details?: Record<string, unknown>;
+    constructor(init: {
+        code?: string;
+        message?: string;
+        closeCode: number;
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    });
+    /** `JSON.stringify(err)` 가 `{}` 가 되지 않도록 한다 (ApiError.toJSON 참조). */
+    toJSON(): Record<string, unknown>;
+}
 
 interface AbortOptions {
     timeout?: number;
@@ -8099,6 +8157,16 @@ declare class RealtimeAPI {
     get transport(): "ws" | "sse" | null;
     private options;
     private retryCount;
+    /**
+     * 재연결 뒤 복구할 구독 상태. 연결이 끊긴 첫 순간에 떠 두고, 재연결이 성공해 복구한 뒤 비운다.
+     *
+     * 재연결 시도가 실패할 때마다 onclose → handleDisconnect 가 다시 불린다. 예전에는 그때마다 구독 맵을
+     * 새로 떴는데, 첫 끊김에서 이미 비워진 맵이라 빈 스냅샷으로 덮였다 — 첫 재연결 시도가 실패하면
+     * (서버 롤링 재시작 등) 재연결에 성공해도 구독이 하나도 복구되지 않았다.
+     */
+    private pendingRestore;
+    /** 첫 연결 전에 direct 원본 힌트를 한 번 물었는지 (primeDirectRealtime). */
+    private directRealtimePrimed;
     private pendingRequests;
     private subscriptions;
     private streamSessions;
@@ -8383,6 +8451,17 @@ declare class RealtimeAPI {
      * ```
      */
     onReadReceipt(category: string, handler: ReadReceiptHandler): () => void;
+    /**
+     * direct(저지연) 원본을 아직 모르면 첫 연결 전에 한 번 묻는다 — `GET /v1/public/edge-hints`.
+     *
+     * direct 원본은 core-server 응답 헤더(`X-CB-Realtime-Direct-Base`)로만 배운다. realtime 만 쓰는
+     * 페이지는 WS 를 열기 전에 REST 를 부르지 않아 배울 기회가 없었고, 첫 연결이 늘 Cloudflare 를 타
+     * 한국 사용자는 미국(LAX)을 거친 ~270ms 로 붙었다(platform-issue 01a15d9d 의 273ms). 응답 헤더는
+     * HttpClient 가 평소처럼 학습한다. 광고 대상이 아니면(해외, 킬 스위치) 빈 응답이라 원래 소켓
+     * URL 로 간다. 실패하거나 느리면(1.5초) 그냥 넘어간다 — 최적화일 뿐 연결의 전제가 아니다.
+     * 세션당 한 번만 묻는다.
+     */
+    private primeDirectRealtime;
     private doConnect;
     private log;
     /**
@@ -8393,6 +8472,11 @@ declare class RealtimeAPI {
     private logError;
     private handleServerMessage;
     private handleDisconnect;
+    /**
+     * 재연결을 멈추고 앱에 알린다 — 서버가 재시도해도 소용없는 이유(자격증명, 할당량)로 거부했거나
+     * 재시도할 수 있는 거부가 maxRetries 를 다 썼다.
+     */
+    private failRealtime;
     /**
      * 이전 구독 상태를 복구합니다.
      * 재연결 성공 후 호출됩니다.
@@ -11757,4 +11841,4 @@ declare class ConnectBase {
     updateConfig(config: Partial<ConnectBaseConfig>): void;
 }
 
-export { AIAPI, type AIChatOptions, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, AIError, type AIErrorCode, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AcceptInvitationResponse, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AgenticSearchProgress, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppMemberDetail, type AppMemberIdentityDetail, type AppMemberIdentitySummary, type AppMemberList, type AppMemberListItem, type AppMemberProviderType, AppMembersAPI, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchOperationResult, type BatchSetPageMetaRequest, type BatchWriteResult, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type ChangePlanPreview, type ChangePlanRequest, type Channel, type ChannelMembership, type ChannelStats, 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 CreateInvitationRequest, type CreateInvitationResponse, type CreateLobbyRequest, type CreateOrganizationRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateRolePayload, type CreateRoleResult, type CreateRoomResult, 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 DeleteBillingKeyResponse, 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, GameError, type GameErrorCode, 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 GeoBoundingBox, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, 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 ListAppMembersOptions, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListPaymentsOptions, 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 MemberChangePasswordRequest, type MemberCredentialMessageResponse, type MemberEmailVerificationConfirmRequest, type MemberEmailVerificationConfirmResponse, type MemberEmailVerificationRequest, type MemberInfoResponse, type MemberPasswordResetConfirmRequest, type MemberPasswordResetRequest, type MemberRedirectOption, type MemberSession, type MemberSessionList, type MemberSessionRevokeResponse, 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 OnPaymentFailure, type OpenDialogOptions, type OpenDialogResult, type Organization, type OrganizationContext, type OrganizationInvitation, type OrganizationMember, type OrganizationMemberList, type OrganizationRole, OrganizationsAPI, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentListItem, type PaymentListResult, type PaymentMode, 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 PostponeBillingRequest, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type ProrationMode, type PublicKeyItem, type PublicKeyPaymentMode, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type PushStatsResult, 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 RoleDetail, type RoleList, type RoleListItem, type RolePermissionItem, type RoleUserItem, RolesAPI, type RoomInfo, type RoomStaleMessage, type RoomSummary, type RoomsResponse, type RotatePublicKeyRequest, type RotatePublicKeyResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptLogEntry, type ScriptLogsResponse, type ScriptMeta, type ScriptMetricsResponse, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type SendSuperChatOptions, type SendSuperChatResponse, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type SpeechRecognizeOptions, type SpeechResult, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StorageUploadProgress, type StreamContentPart, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamImageURLPart, type StreamMessage, type StreamOptions, type StreamSession, type StreamTextPart, 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 SuperChatType, type SyncLostMessage, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionResult, type TransactionWrite, type TransactionWriteResult, 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 UpdateDocumentRequest, type UpdateLobbyRequest, type UpdateOrganizationRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateRolePayload, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoCompleteUploadResponse, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageAccessLevel, 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, detectInAppBrowser, escapeToExternalBrowser, isWebTransportSupported, toAIError, toCreateRoomWire };
+export { AIAPI, type AIChatOptions, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, AIError, type AIErrorCode, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AcceptInvitationResponse, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AgenticSearchProgress, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppMemberDetail, type AppMemberIdentityDetail, type AppMemberIdentitySummary, type AppMemberList, type AppMemberListItem, type AppMemberProviderType, AppMembersAPI, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchOperationResult, type BatchSetPageMetaRequest, type BatchWriteResult, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type ChangePlanPreview, type ChangePlanRequest, type Channel, type ChannelMembership, type ChannelStats, 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 CreateInvitationRequest, type CreateInvitationResponse, type CreateLobbyRequest, type CreateOrganizationRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateRolePayload, type CreateRoleResult, type CreateRoomResult, 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 DeleteBillingKeyResponse, 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, GameError, type GameErrorCode, 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 GeoBoundingBox, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, 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 ListAppMembersOptions, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListPaymentsOptions, 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 MemberChangePasswordRequest, type MemberCredentialMessageResponse, type MemberEmailVerificationConfirmRequest, type MemberEmailVerificationConfirmResponse, type MemberEmailVerificationRequest, type MemberInfoResponse, type MemberPasswordResetConfirmRequest, type MemberPasswordResetRequest, type MemberRedirectOption, type MemberSession, type MemberSessionList, type MemberSessionRevokeResponse, 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 OnPaymentFailure, type OpenDialogOptions, type OpenDialogResult, type Organization, type OrganizationContext, type OrganizationInvitation, type OrganizationMember, type OrganizationMemberList, type OrganizationRole, OrganizationsAPI, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentListItem, type PaymentListResult, type PaymentMode, 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 PostponeBillingRequest, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type ProrationMode, type PublicKeyItem, type PublicKeyPaymentMode, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type PushStatsResult, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, RealtimeConnectionError, type RealtimeConnectionErrorCode, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoleDetail, type RoleList, type RoleListItem, type RolePermissionItem, type RoleUserItem, RolesAPI, type RoomInfo, type RoomStaleMessage, type RoomSummary, type RoomsResponse, type RotatePublicKeyRequest, type RotatePublicKeyResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptLogEntry, type ScriptLogsResponse, type ScriptMeta, type ScriptMetricsResponse, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type SendSuperChatOptions, type SendSuperChatResponse, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type SpeechRecognizeOptions, type SpeechResult, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StorageUploadProgress, type StreamContentPart, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamImageURLPart, type StreamMessage, type StreamOptions, type StreamSession, type StreamTextPart, 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 SuperChatType, type SyncLostMessage, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionResult, type TransactionWrite, type TransactionWriteResult, 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 UpdateDocumentRequest, type UpdateLobbyRequest, type UpdateOrganizationRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateRolePayload, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoCompleteUploadResponse, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageAccessLevel, 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, detectInAppBrowser, escapeToExternalBrowser, isWebTransportSupported, toAIError, toCreateRoomWire };

package/dist/index.d.ts

@@ -152,6 +152,64 @@ declare class GameError extends Error {
     /** `JSON.stringify(err)` 가 `{}` 가 되지 않도록 한다 (ApiError.toJSON 참조). */
     toJSON(): Record<string, unknown>;
 }
+/**
+ * 실시간(WebSocket) 연결 거부 코드. socket-server 가 연결을 받지 않은 이유이고, 대응이 코드마다 다르다.
+ *
+ * | 코드 | 원인 | 재시도 | 권장 대응 |
+ * |------|------|--------|-----------|
+ * | `connection_limit_exceeded` | 플랜의 동시접속 한도 도달 | 가능 | 다른 연결이 끊기면 자리가 난다. `details.current`/`details.limit` 확인, 계속되면 플랜 상향 |
+ * | `quota_exceeded` | 월간 WebSocket 사용 시간 소진 | 불가 | 플랜 업그레이드 전까지 재시도 무의미 |
+ * | `server_at_capacity` | 서버 일시 혼잡 | 가능 | 잠시 후 재시도 |
+ * | `auth_unavailable` | 인증 서버 일시 장애 | 가능 | 잠시 후 재시도 |
+ * | `unauthorized` | 공개 키/액세스 토큰이 유효하지 않음 | 불가 | 키·토큰 확인 (토큰 만료면 새 토큰으로 `connect()`) |
+ * | `forbidden` | 다른 앱의 경로로 접속 | 불가 | 설정 확인 |
+ * | `invalid_user_id` | 공개 키 연결에 UUID 형식 `userId` | 불가 | `accessToken` 을 쓰거나 UUID 가 아닌 식별자 사용 |
+ * | `internal_error` | 서버 설정 오류 | 가능 | 잠시 후 재시도 |
+ */
+type RealtimeConnectionErrorCode = "connection_limit_exceeded" | "quota_exceeded" | "server_at_capacity" | "auth_unavailable" | "unauthorized" | "forbidden" | "invalid_user_id" | "internal_error" | (string & {});
+/**
+ * 서버가 이유를 밝히고 실시간 연결을 거부했을 때 `cb.realtime.connect()` 가 던지는 에러.
+ *
+ * 브라우저의 WebSocket API 는 실패한 핸드셰이크의 HTTP 상태를 읽을 수 없어, 예전에는 동시접속
+ * 초과도 인증 실패도 "Connection timeout"/"Failed to connect" 로만 보였고 SDK 는 SSE 폴백으로
+ * 넘어가 subscribe/send 가 나중에야 이유 없이 실패했다(platform-issue 01a15d9d). 이제 서버가
+ * 연결을 받은 뒤 거부 이유를 보내고 4000+HTTP상태 close 코드(예: 4401, 4402, 4503)로 닫는다.
+ *
+ * - 거부는 SSE 폴백 대상이 아니다 — 네트워크는 정상이고 서버가 받지 않은 것이다.
+ * - 자동 재연결 중에 받은 거부는 `retryable` 이면 백오프로 계속 시도하고, 아니면 재연결을 멈추고
+ *   `cb.realtime.onError` 로 이 에러를 알린다.
+ *
+ * ```ts
+ * try {
+ *   await cb.realtime.connect()
+ * } catch (e) {
+ *   if (e instanceof RealtimeConnectionError) {
+ *     if (e.code === 'connection_limit_exceeded') showFull(e.details?.limit)
+ *     else if (e.retryable) setTimeout(() => cb.realtime.connect(), 5000)
+ *     else showConfigError(e.message)
+ *   }
+ * }
+ * ```
+ */
+declare class RealtimeConnectionError extends Error {
+    /** 문서화된 거부 코드. 분기 기준은 항상 이 필드다. */
+    code: RealtimeConnectionErrorCode;
+    /** WebSocket close 코드 (4000 + 서버의 HTTP 상태). */
+    closeCode: number;
+    /** 시간차를 두고 다시 연결하면 성공할 수 있는지. */
+    retryable: boolean;
+    /** 거부 상세 (예: connection_limit_exceeded 의 `current`/`limit`, quota_exceeded 의 `quota`/`unit`). */
+    details?: Record<string, unknown>;
+    constructor(init: {
+        code?: string;
+        message?: string;
+        closeCode: number;
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    });
+    /** `JSON.stringify(err)` 가 `{}` 가 되지 않도록 한다 (ApiError.toJSON 참조). */
+    toJSON(): Record<string, unknown>;
+}
 
 interface AbortOptions {
     timeout?: number;
@@ -8099,6 +8157,16 @@ declare class RealtimeAPI {
     get transport(): "ws" | "sse" | null;
     private options;
     private retryCount;
+    /**
+     * 재연결 뒤 복구할 구독 상태. 연결이 끊긴 첫 순간에 떠 두고, 재연결이 성공해 복구한 뒤 비운다.
+     *
+     * 재연결 시도가 실패할 때마다 onclose → handleDisconnect 가 다시 불린다. 예전에는 그때마다 구독 맵을
+     * 새로 떴는데, 첫 끊김에서 이미 비워진 맵이라 빈 스냅샷으로 덮였다 — 첫 재연결 시도가 실패하면
+     * (서버 롤링 재시작 등) 재연결에 성공해도 구독이 하나도 복구되지 않았다.
+     */
+    private pendingRestore;
+    /** 첫 연결 전에 direct 원본 힌트를 한 번 물었는지 (primeDirectRealtime). */
+    private directRealtimePrimed;
     private pendingRequests;
     private subscriptions;
     private streamSessions;
@@ -8383,6 +8451,17 @@ declare class RealtimeAPI {
      * ```
      */
     onReadReceipt(category: string, handler: ReadReceiptHandler): () => void;
+    /**
+     * direct(저지연) 원본을 아직 모르면 첫 연결 전에 한 번 묻는다 — `GET /v1/public/edge-hints`.
+     *
+     * direct 원본은 core-server 응답 헤더(`X-CB-Realtime-Direct-Base`)로만 배운다. realtime 만 쓰는
+     * 페이지는 WS 를 열기 전에 REST 를 부르지 않아 배울 기회가 없었고, 첫 연결이 늘 Cloudflare 를 타
+     * 한국 사용자는 미국(LAX)을 거친 ~270ms 로 붙었다(platform-issue 01a15d9d 의 273ms). 응답 헤더는
+     * HttpClient 가 평소처럼 학습한다. 광고 대상이 아니면(해외, 킬 스위치) 빈 응답이라 원래 소켓
+     * URL 로 간다. 실패하거나 느리면(1.5초) 그냥 넘어간다 — 최적화일 뿐 연결의 전제가 아니다.
+     * 세션당 한 번만 묻는다.
+     */
+    private primeDirectRealtime;
     private doConnect;
     private log;
     /**
@@ -8393,6 +8472,11 @@ declare class RealtimeAPI {
     private logError;
     private handleServerMessage;
     private handleDisconnect;
+    /**
+     * 재연결을 멈추고 앱에 알린다 — 서버가 재시도해도 소용없는 이유(자격증명, 할당량)로 거부했거나
+     * 재시도할 수 있는 거부가 maxRetries 를 다 썼다.
+     */
+    private failRealtime;
     /**
      * 이전 구독 상태를 복구합니다.
      * 재연결 성공 후 호출됩니다.
@@ -11757,4 +11841,4 @@ declare class ConnectBase {
     updateConfig(config: Partial<ConnectBaseConfig>): void;
 }
 
-export { AIAPI, type AIChatOptions, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, AIError, type AIErrorCode, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AcceptInvitationResponse, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AgenticSearchProgress, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppMemberDetail, type AppMemberIdentityDetail, type AppMemberIdentitySummary, type AppMemberList, type AppMemberListItem, type AppMemberProviderType, AppMembersAPI, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchOperationResult, type BatchSetPageMetaRequest, type BatchWriteResult, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type ChangePlanPreview, type ChangePlanRequest, type Channel, type ChannelMembership, type ChannelStats, 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 CreateInvitationRequest, type CreateInvitationResponse, type CreateLobbyRequest, type CreateOrganizationRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateRolePayload, type CreateRoleResult, type CreateRoomResult, 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 DeleteBillingKeyResponse, 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, GameError, type GameErrorCode, 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 GeoBoundingBox, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, 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 ListAppMembersOptions, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListPaymentsOptions, 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 MemberChangePasswordRequest, type MemberCredentialMessageResponse, type MemberEmailVerificationConfirmRequest, type MemberEmailVerificationConfirmResponse, type MemberEmailVerificationRequest, type MemberInfoResponse, type MemberPasswordResetConfirmRequest, type MemberPasswordResetRequest, type MemberRedirectOption, type MemberSession, type MemberSessionList, type MemberSessionRevokeResponse, 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 OnPaymentFailure, type OpenDialogOptions, type OpenDialogResult, type Organization, type OrganizationContext, type OrganizationInvitation, type OrganizationMember, type OrganizationMemberList, type OrganizationRole, OrganizationsAPI, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentListItem, type PaymentListResult, type PaymentMode, 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 PostponeBillingRequest, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type ProrationMode, type PublicKeyItem, type PublicKeyPaymentMode, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type PushStatsResult, 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 RoleDetail, type RoleList, type RoleListItem, type RolePermissionItem, type RoleUserItem, RolesAPI, type RoomInfo, type RoomStaleMessage, type RoomSummary, type RoomsResponse, type RotatePublicKeyRequest, type RotatePublicKeyResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptLogEntry, type ScriptLogsResponse, type ScriptMeta, type ScriptMetricsResponse, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type SendSuperChatOptions, type SendSuperChatResponse, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type SpeechRecognizeOptions, type SpeechResult, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StorageUploadProgress, type StreamContentPart, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamImageURLPart, type StreamMessage, type StreamOptions, type StreamSession, type StreamTextPart, 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 SuperChatType, type SyncLostMessage, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionResult, type TransactionWrite, type TransactionWriteResult, 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 UpdateDocumentRequest, type UpdateLobbyRequest, type UpdateOrganizationRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateRolePayload, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoCompleteUploadResponse, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageAccessLevel, 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, detectInAppBrowser, escapeToExternalBrowser, isWebTransportSupported, toAIError, toCreateRoomWire };
+export { AIAPI, type AIChatOptions, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, AIError, type AIErrorCode, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AcceptInvitationResponse, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AgenticSearchProgress, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppMemberDetail, type AppMemberIdentityDetail, type AppMemberIdentitySummary, type AppMemberList, type AppMemberListItem, type AppMemberProviderType, AppMembersAPI, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchOperationResult, type BatchSetPageMetaRequest, type BatchWriteResult, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type ChangePlanPreview, type ChangePlanRequest, type Channel, type ChannelMembership, type ChannelStats, 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 CreateInvitationRequest, type CreateInvitationResponse, type CreateLobbyRequest, type CreateOrganizationRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateRolePayload, type CreateRoleResult, type CreateRoomResult, 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 DeleteBillingKeyResponse, 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, GameError, type GameErrorCode, 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 GeoBoundingBox, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, 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 ListAppMembersOptions, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListPaymentsOptions, 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 MemberChangePasswordRequest, type MemberCredentialMessageResponse, type MemberEmailVerificationConfirmRequest, type MemberEmailVerificationConfirmResponse, type MemberEmailVerificationRequest, type MemberInfoResponse, type MemberPasswordResetConfirmRequest, type MemberPasswordResetRequest, type MemberRedirectOption, type MemberSession, type MemberSessionList, type MemberSessionRevokeResponse, 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 OnPaymentFailure, type OpenDialogOptions, type OpenDialogResult, type Organization, type OrganizationContext, type OrganizationInvitation, type OrganizationMember, type OrganizationMemberList, type OrganizationRole, OrganizationsAPI, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentListItem, type PaymentListResult, type PaymentMode, 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 PostponeBillingRequest, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type ProrationMode, type PublicKeyItem, type PublicKeyPaymentMode, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type PushStatsResult, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, RealtimeConnectionError, type RealtimeConnectionErrorCode, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoleDetail, type RoleList, type RoleListItem, type RolePermissionItem, type RoleUserItem, RolesAPI, type RoomInfo, type RoomStaleMessage, type RoomSummary, type RoomsResponse, type RotatePublicKeyRequest, type RotatePublicKeyResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptLogEntry, type ScriptLogsResponse, type ScriptMeta, type ScriptMetricsResponse, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type SendSuperChatOptions, type SendSuperChatResponse, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type SpeechRecognizeOptions, type SpeechResult, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StorageUploadProgress, type StreamContentPart, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamImageURLPart, type StreamMessage, type StreamOptions, type StreamSession, type StreamTextPart, 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 SuperChatType, type SyncLostMessage, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionResult, type TransactionWrite, type TransactionWriteResult, 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 UpdateDocumentRequest, type UpdateLobbyRequest, type UpdateOrganizationRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateRolePayload, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoCompleteUploadResponse, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageAccessLevel, 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, detectInAppBrowser, escapeToExternalBrowser, isWebTransportSupported, toAIError, toCreateRoomWire };

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   GameRoomTransport: () => GameRoomTransport,
   NativeAPI: () => NativeAPI,
   OrganizationsAPI: () => OrganizationsAPI,
+  RealtimeConnectionError: () => RealtimeConnectionError,
   RolesAPI: () => RolesAPI,
   SessionManager: () => SessionManager,
   VideoProcessingError: () => VideoProcessingError,
@@ -282,6 +283,30 @@ var GameError = class extends Error {
     };
   }
 };
+var RealtimeConnectionError = class extends Error {
+  constructor(init) {
+    super(init.message || init.code || "Realtime connection rejected");
+    this.name = "RealtimeConnectionError";
+    this.code = init.code || "unknown";
+    this.closeCode = init.closeCode;
+    this.retryable = init.retryable ?? isRetryableRealtimeRejection(this.code);
+    this.details = init.details;
+  }
+  /** `JSON.stringify(err)` 가 `{}` 가 되지 않도록 한다 (ApiError.toJSON 참조). */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      closeCode: this.closeCode,
+      retryable: this.retryable,
+      details: this.details
+    };
+  }
+};
+function isRetryableRealtimeRejection(code) {
+  return code === "connection_limit_exceeded" || code === "server_at_capacity" || code === "auth_unavailable" || code === "internal_error";
+}
 
 // src/api/ai.ts
 function aiErrorToApiError(err) {
@@ -7924,6 +7949,18 @@ var QueueAPI = class {
 
 // src/api/realtime.ts
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function toConnectionRejection(msg) {
+  if (msg.event !== "error" || msg.request_id) return null;
+  const data = msg.data;
+  if (!data || typeof data.close_code !== "number") return null;
+  return new RealtimeConnectionError({
+    code: data.code,
+    message: data.message || msg.error,
+    closeCode: data.close_code,
+    retryable: data.retryable,
+    details: data.details
+  });
+}
 var RealtimeAPI = class {
   constructor(http, socketUrl) {
     this.ws = null;
@@ -7951,6 +7988,16 @@ var RealtimeAPI = class {
       fallback: "sse"
     };
     this.retryCount = 0;
+    /**
+     * 재연결 뒤 복구할 구독 상태. 연결이 끊긴 첫 순간에 떠 두고, 재연결이 성공해 복구한 뒤 비운다.
+     *
+     * 재연결 시도가 실패할 때마다 onclose → handleDisconnect 가 다시 불린다. 예전에는 그때마다 구독 맵을
+     * 새로 떴는데, 첫 끊김에서 이미 비워진 맵이라 빈 스냅샷으로 덮였다 — 첫 재연결 시도가 실패하면
+     * (서버 롤링 재시작 등) 재연결에 성공해도 구독이 하나도 복구되지 않았다.
+     */
+    this.pendingRestore = null;
+    /** 첫 연결 전에 direct 원본 힌트를 한 번 물었는지 (primeDirectRealtime). */
+    this.directRealtimePrimed = false;
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.subscriptions = /* @__PURE__ */ new Map();
     this.streamSessions = /* @__PURE__ */ new Map();
@@ -7994,7 +8041,7 @@ var RealtimeAPI = class {
     if (this.state === "connected") {
       return;
     }
-    if (this.state === "connecting" && this.connectPromise) {
+    if (this.connectPromise) {
       return this.connectPromise;
     }
     this.options = { ...this.options, ...options };
@@ -8006,10 +8053,15 @@ var RealtimeAPI = class {
         `Invalid userId: "${this.userId}" looks like a UUID, which is reserved for authenticated members. Pass that member's accessToken (JWT) instead of userId+publicKey, or use a non-UUID identifier for anonymous/guest connections.`
       );
     }
-    this.connectPromise = this.doConnect();
+    this.connectPromise = this.primeDirectRealtime().then(
+      () => this.doConnect()
+    );
     try {
       await this.connectPromise;
     } catch (e) {
+      if (e instanceof RealtimeConnectionError) {
+        throw e;
+      }
       const hasAuth = !!(this.options.accessToken || this.http.getPublicKey());
       if (this.options.fallback !== "none" && hasAuth) {
         this.activateSseFallback(e);
@@ -8038,6 +8090,7 @@ var RealtimeAPI = class {
     this.activeTransport = "sse";
     this.state = "connected";
     this.retryCount = 0;
+    this.pendingRestore = null;
     this.log(
       `WS unavailable (${causeMsg}); using SSE fallback transport for AI streaming`
     );
@@ -8094,6 +8147,7 @@ var RealtimeAPI = class {
     this._appId = null;
     this.retryCount = 0;
     this.connectPromise = null;
+    this.pendingRestore = null;
   }
   /**
    * 카테고리 구독
@@ -8876,6 +8930,30 @@ var RealtimeAPI = class {
     };
   }
   // Private methods
+  /**
+   * direct(저지연) 원본을 아직 모르면 첫 연결 전에 한 번 묻는다 — `GET /v1/public/edge-hints`.
+   *
+   * direct 원본은 core-server 응답 헤더(`X-CB-Realtime-Direct-Base`)로만 배운다. realtime 만 쓰는
+   * 페이지는 WS 를 열기 전에 REST 를 부르지 않아 배울 기회가 없었고, 첫 연결이 늘 Cloudflare 를 타
+   * 한국 사용자는 미국(LAX)을 거친 ~270ms 로 붙었다(platform-issue 01a15d9d 의 273ms). 응답 헤더는
+   * HttpClient 가 평소처럼 학습한다. 광고 대상이 아니면(해외, 킬 스위치) 빈 응답이라 원래 소켓
+   * URL 로 간다. 실패하거나 느리면(1.5초) 그냥 넘어간다 — 최적화일 뿐 연결의 전제가 아니다.
+   * 세션당 한 번만 묻는다.
+   */
+  async primeDirectRealtime() {
+    if (this.directRealtimePrimed) return;
+    this.directRealtimePrimed = true;
+    if (this.http.getDirectRealtimeBaseUrl() || !this.http.getPublicKey()) {
+      return;
+    }
+    try {
+      await this.http.get("/v1/public/edge-hints", { timeout: 1500 });
+    } catch (e) {
+      this.log(
+        `edge hint lookup failed, using default socket URL: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+  }
   async doConnect() {
     return new Promise((resolve, reject) => {
       this.state = "connecting";
@@ -8904,7 +8982,9 @@ var RealtimeAPI = class {
       if (this.userId) {
         url += `&user_id=${encodeURIComponent(this.userId)}`;
       }
+      url += "&reject_mode=close";
       let settled = false;
+      let rejection = null;
       const timeoutId = setTimeout(() => {
         if (!settled) {
           settled = true;
@@ -8932,6 +9012,11 @@ var RealtimeAPI = class {
           for (const line of messages) {
             try {
               const msg = JSON.parse(line);
+              const rejected = toConnectionRejection(msg);
+              if (rejected && !settled) {
+                rejection = rejected;
+                continue;
+              }
               this.handleServerMessage(msg, () => {
                 if (!settled) {
                   settled = true;
@@ -8949,6 +9034,30 @@ var RealtimeAPI = class {
           this.log(
             `WebSocket closed: code=${event.code}, reason=${event.reason}`
           );
+          if (event.code >= 4e3 && event.code <= 4999) {
+            const err = rejection ?? new RealtimeConnectionError({
+              code: event.reason || void 0,
+              closeCode: event.code
+            });
+            const wasConnected = this.state === "connected";
+            if (!settled) {
+              settled = true;
+              clearTimeout(timeoutId);
+            }
+            this.ws = null;
+            if (wasConnected) {
+              if (err.retryable) {
+                this.handleDisconnect();
+              } else {
+                this.failRealtime(err);
+              }
+              return;
+            }
+            this.state = "disconnected";
+            this.notifyStateChange();
+            reject(err);
+            return;
+          }
           if (!settled && this.state === "connecting") {
             settled = true;
             clearTimeout(timeoutId);
@@ -9195,20 +9304,23 @@ var RealtimeAPI = class {
       }
     });
     this.streamSessions.clear();
-    const previousSubscriptions = /* @__PURE__ */ new Map();
-    for (const [category, sub] of this.subscriptions) {
-      previousSubscriptions.set(category, [...sub.handlers]);
+    if (!this.pendingRestore) {
+      const subscriptions = /* @__PURE__ */ new Map();
+      for (const [category, sub] of this.subscriptions) {
+        subscriptions.set(category, [...sub.handlers]);
+      }
+      const presence = /* @__PURE__ */ new Map();
+      for (const [userId, handlers] of this.presenceSubscriptions) {
+        presence.set(userId, [...handlers]);
+      }
+      const typing = /* @__PURE__ */ new Map();
+      for (const [roomId, handlers] of this.typingHandlers) {
+        typing.set(roomId, [...handlers]);
+      }
+      this.pendingRestore = { subscriptions, presence, typing };
     }
     this.subscriptions.clear();
-    const previousPresenceSubscriptions = /* @__PURE__ */ new Map();
-    for (const [userId, handlers] of this.presenceSubscriptions) {
-      previousPresenceSubscriptions.set(userId, [...handlers]);
-    }
     this.presenceSubscriptions.clear();
-    const previousTypingHandlers = /* @__PURE__ */ new Map();
-    for (const [roomId, handlers] of this.typingHandlers) {
-      previousTypingHandlers.set(roomId, [...handlers]);
-    }
     this.typingHandlers.clear();
     if (this.retryCount < this.options.maxRetries) {
       this.state = "reconnecting";
@@ -9220,16 +9332,29 @@ var RealtimeAPI = class {
       );
       setTimeout(async () => {
         if (this.sseFallbackActive) return;
+        if (this.state !== "reconnecting") return;
         try {
           await this.doConnect();
           this.log("Reconnected successfully, restoring subscriptions...");
-          await this.restoreSubscriptions(
-            previousSubscriptions,
-            previousPresenceSubscriptions,
-            previousTypingHandlers
-          );
+          const snapshot = this.pendingRestore;
+          this.pendingRestore = null;
+          if (snapshot) {
+            await this.restoreSubscriptions(
+              snapshot.subscriptions,
+              snapshot.presence,
+              snapshot.typing
+            );
+          }
         } catch (e) {
           this.logError("Reconnect failed", e);
+          if (e instanceof RealtimeConnectionError) {
+            if (e.retryable && this.retryCount < this.options.maxRetries) {
+              this.handleDisconnect();
+            } else {
+              this.failRealtime(e);
+            }
+            return;
+          }
           if (this.retryCount >= this.options.maxRetries && this.options.fallback !== "none" && !this.sseFallbackActive) {
             this.activateSseFallback(e);
           }
@@ -9247,6 +9372,18 @@ var RealtimeAPI = class {
       }
     }
   }
+  /**
+   * 재연결을 멈추고 앱에 알린다 — 서버가 재시도해도 소용없는 이유(자격증명, 할당량)로 거부했거나
+   * 재시도할 수 있는 거부가 maxRetries 를 다 썼다.
+   */
+  failRealtime(err) {
+    this.pendingRestore = null;
+    this.ws = null;
+    this._connectionId = null;
+    this.state = "disconnected";
+    this.notifyStateChange();
+    this.notifyError(err);
+  }
   /**
    * 이전 구독 상태를 복구합니다.
    * 재연결 성공 후 호출됩니다.
@@ -14224,6 +14361,7 @@ var index_default = ConnectBase;
   GameRoomTransport,
   NativeAPI,
   OrganizationsAPI,
+  RealtimeConnectionError,
   RolesAPI,
   SessionManager,
   VideoProcessingError,