Gmail watch source

/** Structural subset of an already-authenticated Gmail client; no SDK or credentials are loaded. */
export interface GmailWatchClient {
    users: {
        getProfile(params: {
            userId: string;
        }, options: RequestOptions): Result<{
            historyId?: string | null;
            emailAddress?: string | null;
        }>;
        watch(params: {
            userId: string;
            requestBody: {
                topicName: string;
                labelIds?: string[];
                labelFilterBehavior?: "INCLUDE";
            };
        }, options: RequestOptions): Result<{
            historyId?: string | null;
            expiration?: string | null;
        }>;
        stop(params: {
            userId: string;
        }, options: RequestOptions): Promise<unknown>;
        history: {
            list(params: {
                userId: string;
                startHistoryId: string;
                historyTypes: string[];
                maxResults: number;
                pageToken?: string;
            }, options: RequestOptions): Result<{
                historyId?: string | null;
                nextPageToken?: string | null;
                history?: Array<{
                    id?: string | null;
                    messagesAdded?: Array<{
                        message?: {
                            id?: string | null;
                            labelIds?: string[] | null;
                        } | null;
                    }>;
                }>;
            }>;
        };
        messages: {
            list(params: {
                userId: string;
                maxResults: number;
                pageToken?: string;
                labelIds?: string[];
            }, options: RequestOptions): Result<{
                messages?: Array<{
                    id?: string | null;
                }>;
                nextPageToken?: string | null;
            }>;
            get(params: {
                userId: string;
                id: string;
                format: "metadata";
                metadataHeaders: string[];
            }, options: RequestOptions): Result<GmailMessage>;
        };
    };
}

export interface GmailWatchOptions {
    id: string;
    mailbox: string;
    identity: WatchIdentity;
    topicName: string;
    labelIds?: string[];
    client: GmailWatchClient;
    /** Host verifies Pub/Sub signature, audience and subscription ownership before decoding. */
    verifyPush?: (raw: unknown) => Promise<{
        identity: WatchIdentity;
        messageId: string;
        data: {
            emailAddress: string;
            historyId: string;
        };
    }>;
}

/** Optional Gmail source: daily renewal/polling are scheduled by DurableWatch, not in this constructor. */
export declare function gmailWatchSource(options: GmailWatchOptions): WatchSource;

type RequestOptions = {
    signal: AbortSignal;
};

type Result<T> = Promise<{
    data: T;
}>;

interface GmailMessage {
    id?: string | null;
    internalDate?: string | null;
    snippet?: string | null;
    payload?: {
        headers?: Array<{
            name?: string | null;
            value?: string | null;
        }>;
    } | null;
}