@vibexnpm/talkx 8.4.1 → 8.5.0

package/dist/index.d.ts

@@ -1340,6 +1340,71 @@ export interface RoomUnreadUpdatedEvent {
     unreadVersion: number;
 }
 
+/** Gmail 새 메일 미리보기 — 서버 `MAIL_CHANGED.messages[]` 원소. 본문은 없다. */
+export interface MailPreview {
+    messageId: string;
+    threadId?: string | null;
+    from?: { name?: string | null; email: string } | null;
+    subject?: string | null;
+    /** ISO-8601 UTC. */
+    receivedAt?: string | null;
+}
+
+/**
+ * `mailChanged` 이벤트 — 서버 `/user/queue/mail` 그대로. 받으면 열려 있는 메일 목록·안읽은 수를 다시 읽는다.
+ * 읽음·보관 같은 변화면 `messages` 가 비어 있다(새 메일 알림을 띄우지 않는다).
+ */
+export interface MailChangedEvent {
+    eventType: 'MAIL_CHANGED';
+    connectionId: string;
+    /** 받은메일함 안읽은 수, 모르면 -1. */
+    inboxUnread: number;
+    newMessages: number;
+    /** true 면 놓친 변화가 있을 수 있다 — 목록을 첫 쪽부터 다시 읽는다. */
+    resync: boolean;
+    timestamp: string;
+    messages: MailPreview[];
+}
+
+/**
+ * `newMail` 이벤트 — 새 메일 한 통. 웹소켓 미리보기(`source: 'socket'`)와 포그라운드 FCM 메일 푸시(`source: 'push'`)를
+ * `(projectId, connectionId, messageId)` 로 합쳐 메일마다 한 번만 온다.
+ */
+export interface NewMailEvent {
+    projectId: string | null;
+    connectionId: string;
+    messageId: string;
+    threadId: string | null;
+    /** 보낸 사람 표시(이름, 없으면 주소). */
+    sender: string | null;
+    /** 웹소켓으로 왔을 때만. */
+    from: { name?: string | null; email: string } | null;
+    subject: string | null;
+    /** 웹소켓으로 왔을 때만(ISO-8601 UTC). */
+    receivedAt: string | null;
+    source: 'socket' | 'push';
+}
+
+/**
+ * `newMailSummary` 이벤트 — 한 번에 4통 이상 온 묶음 푸시(포그라운드). 받은메일함을 다시 읽는다.
+ * 묶은 메일 중 아직 `newMail` 로 알리지 않은 것만 센다 — 전부 알린 메일이면 오지 않는다.
+ */
+export interface NewMailSummaryEvent {
+    projectId: string | null;
+    connectionId: string;
+    /** 처음 알리는 메일 수(구버전 서버의 묶음이면 서버가 준 건수). */
+    count: number | null;
+    /** 처음 알리는 메일 ID(구버전 서버의 묶음이면 빈 배열). */
+    messageIds: string[];
+    source: 'push';
+}
+
+/** 알림 클릭으로 열린 앱이 꺼내는 메일 이동 — `messageId` 가 없으면(묶음 알림) 받은메일함으로. */
+export interface PendingMail {
+    connectionId: string;
+    messageId: string | null;
+}
+
 /** 포그라운드 푸시 알림 payload. */
 export interface PushNotificationPayload {
     title: string;
@@ -1980,6 +2045,9 @@ export interface TalkFlowClientEvents {
     roomListRoomUpdated: RoomListUpdateEvent;
     /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
     roomListUnreadUpdated: RoomUnreadUpdatedEvent;
+    mailSubscribed: Record<string, unknown>;
+    mailUnsubscribed: Record<string, unknown>;
+    mailChanged: MailChangedEvent;
     retentionCleanup: RetentionCleanupPayload;
 
     // 갭 복구 — 복구된 메시지 자체는 일반 chatMessage 로 재생되므로 아래는 모두 선택 구독용.
@@ -2010,6 +2078,10 @@ export interface TalkFlowClientEvents {
      */
     pushFailed: PushFailedPayload;
     pushNotification: PushNotificationPayload;
+    /** Gmail 새 메일 한 통 — 웹소켓·포그라운드 푸시를 합쳐 메일마다 한 번. 메일 푸시는 pushNotification 으로 오지 않는다. */
+    newMail: NewMailEvent;
+    /** Gmail 묶음 푸시(4통 이상) — 포그라운드. */
+    newMailSummary: NewMailSummaryEvent;
 
     // WebRTC (re-emit from WebRTCClient)
     localStreamStarted: unknown;
@@ -2087,6 +2159,9 @@ export interface ChatClientEvents {
     roomListRoomUpdated: RoomListUpdateEvent;
     /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
     roomListUnreadUpdated: RoomUnreadUpdatedEvent;
+    mailSubscribed: Record<string, unknown>;
+    mailUnsubscribed: Record<string, unknown>;
+    mailChanged: MailChangedEvent;
     retentionCleanup: RetentionCleanupPayload;
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
@@ -2297,6 +2372,10 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     subscribeRoomList(): Promise<void>;
     unsubscribeRoomList(): void;
     isRoomListSubscribed(): boolean;
+    /** Gmail 메일함 변화 구독(`/user/queue/mail`) — 자동 구독하지 않는다. */
+    subscribeMail(): Promise<void>;
+    unsubscribeMail(): void;
+    isMailSubscribed(): boolean;
     getSubscribedRooms(): string[];
     isSubscribed(roomId: string): boolean;
 
@@ -2447,6 +2526,8 @@ export const PushErrorCode: {
 
 export class PushManager {
     consumePendingRoom(): Promise<string | null>;
+    /** 알림 클릭(cold start)으로 저장된 Gmail 메일 이동을 꺼내고 지운다 — 10분 안의 것만. */
+    consumePendingMail(): Promise<PendingMail | null>;
     reset(): void;
     getToken(): string | null;
     isEnabled(): boolean;
@@ -2457,6 +2538,7 @@ export class PushManager {
     /** 현재 디바이스의 푸시 수신 여부 토글. */
     setCurrentDeviceEnabled(enabled: boolean): Promise<void>;
     static consumePendingRoom(projectId?: string): Promise<string | null>;
+    static consumePendingMail(projectId?: string): Promise<PendingMail | null>;
     /**
      * 현재 브라우저의 푸시 권한 상태. 인스턴스 없이도 호출 가능.
      */
@@ -2588,6 +2670,8 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     /** 푸시 상태 초기화 — 로그아웃 또는 사용자 전환 시 호출. logout() 내부에서 자동 호출됨. */
     resetPush(): void;
     consumePendingRoom(): Promise<string | null>;
+    /** 알림 클릭(cold start)으로 저장된 Gmail 메일 이동을 꺼내고 지운다 — 앱 부팅 때 한 번. */
+    consumePendingMail(): Promise<PendingMail | null>;
     /** 현재 디바이스의 푸시 수신 여부 토글. enable 선행 안 됐으면 undefined 반환. */
     setCurrentDeviceEnabled(enabled: boolean): Promise<void> | undefined;
     /** 특정 디바이스 토글 (관리 UI 용). enable 선행 안 됐으면 undefined 반환. */
@@ -2750,6 +2834,10 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     subscribeRoomList(): Promise<void>;
     unsubscribeRoomList(): void;
     isRoomListSubscribed(): boolean;
+    /** Gmail 메일함 변화 구독(`/user/queue/mail`) — 자동 구독하지 않는다. */
+    subscribeMail(): Promise<void>;
+    unsubscribeMail(): void;
+    isMailSubscribed(): boolean;
     getSubscribedRooms(): string[];
     isSubscribed(roomId: string): boolean;