t-comm/lib/qq-mp/types.d.ts

专业、稳定、纯粹的工具库

/**
 * 微信小程序/小游戏中 QQ 登录相关类型定义
 *
 * 数据来源：腾讯 QQ 小程序登录后通过 wx.navigateToMiniProgram 的回调
 * 在 App.onShow 的 options.referrerInfo.extraData 中携带票据信息
 *
 * 字段以现网真实数据为准。
 */
/**
 * 单条票据原始结构（来自 referrerInfo.extraData.tickets[i]）
 */
export interface QQRawTicket {
    /** 票据名称，目前固定为 access_token，不区分大小写 */
    name: 'access_token' | string;
    /** 票据值（access_token 实际值） */
    ticket: string;
    /** QQ 互联 appid（请求时由 launchQQMP 的 extraData.tickets[i].appid 决定） */
    appid: string | number;
    /** QQ 用户 openid */
    openid: string;
    /** 刷新 token，用于过期后续期 */
    refresh_token: string;
    /** 票据有效期（单位：秒），可选 */
    expires_in?: number;
    /** 是否为新用户，可选 */
    is_new?: boolean;
    /** 后端透传字段 */
    [key: string]: any;
}
/**
 * referrerInfo.extraData 原始结构
 */
export interface QQReferrerExtraData {
    /** 状态码：0 表示成功 */
    retcode: number;
    /** 票据列表 */
    tickets: QQRawTicket[];
    /** QQ 小程序透传字段 */
    [key: string]: any;
}
/**
 * referrerInfo 原始结构
 */
export interface QQReferrerInfo {
    /** 来源小程序的 appId（应等于腾讯 QQ 小程序 appId） */
    appId: string;
    /** QQ 小程序透传的数据 */
    extraData?: QQReferrerExtraData;
    /** 其他字段 */
    [key: string]: any;
}
/**
 * App.onShow 回调参数（最小可用子集）
 */
export interface QQOnShowOptions {
    referrerInfo?: QQReferrerInfo;
    query?: Record<string, any>;
    scene?: number;
    path?: string;
    [key: string]: any;
}
/**
 * 提取后的 QQ 登录票据信息（供业务侧使用）
 */
export interface QQTicketInfo {
    /** QQ 用户 openid */
    qqOpenid: string;
    /** access_token 票据值 */
    qqAccessToken: string;
    /** 刷新 token */
    qqRefreshToken: string;
    /** QQ 互联 appid */
    qqAppid: string | number;
    /** 票据有效期（秒），可选 */
    qqExpiresIn?: number;
    /** 是否为新用户，可选 */
    qqIsNew?: boolean;
}
/**
 * 简易 storage 接口（兼容 wx.setStorageSync / oops.storage 等）
 */
export interface QQStorageLike {
    set(key: string, value: any): void;
    get<T = any>(key: string): T | undefined;
    remove?(key: string): void;
}
/**
 * 通用 post 请求函数签名
 *
 * 与 @tencent/pmd-network、t-comm/cocos/manager 兼容
 */
export type QQPostFn = <T = any>(args: {
    url: string;
    reqData?: Record<string, any>;
    [key: string]: any;
}) => Promise<T>;
/**
 * QueryUserInfo 接口的最小响应结构（业务可自行扩展具体类型）
 */
export interface QQQueryUserInfoRsp {
    user_info?: {
        uid?: string;
        nick?: string;
        header?: string;
        utype?: number;
        [key: string]: any;
    };
    [key: string]: any;
}
/**
 * launchQQMP 的入参
 */
export interface LaunchQQMPOptions {
    /** QQ 互联 appid（必填） */
    qqAppId: string | number;
    /** 腾讯 QQ 小程序 appId，默认 wx26da53d900421226 */
    qqMpAppId?: string;
    /** QQ 登录页路径，默认 pagesLogin/pages/login/login */
    loginPath?: string;
    /** 是否强制输入密码（不允许快速登录），默认 false */
    forcePwd?: boolean;
    /** 后台异常状态码列表，会透传给 QQ 小程序 */
    retcodes?: number[];
    /** 体验版：'release' | 'trial' | 'develop'，默认不传 */
    envVersion?: 'release' | 'trial' | 'develop';
}
/**
 * handleQQLoginOnShow 的入参
 */
export interface HandleQQLoginOnShowOptions {
    /** 腾讯 QQ 小程序 appId，默认 wx26da53d900421226 */
    qqMpAppId?: string;
    /** 自定义 storage，默认使用 wx.setStorageSync */
    storage?: QQStorageLike;
    /**
     * 票据写入的 storage key
     *
     * **重要**：必须与业务方的 loginInfo（cocos `loginMp` 写入的 logininfo）所用 key 区分开，
     * 否则票据会把已有的登录态覆盖掉。建议使用形如 `${loginInfoStorageKey}__qq_ticket` 的独立 key。
     */
    storageKey: string;
}
/**
 * queryQQLoginUserInfo 的入参
 */
export interface QueryQQLoginUserInfoOptions {
    /** 接口完整 host（含协议，无末尾斜杠），如 https://a.igame.qq.com */
    host: string | (() => string);
    /** post 请求方法（必填） */
    post: QQPostFn;
    /** QQ 票据信息（必填） */
    ticketInfo: QQTicketInfo;
    /** 接口路径，默认 pmdtrpc.commcgi.user.user/QueryUserInfo */
    apiPath?: string;
    /** 兜底 QQ 互联 appid（票据中无 appid 时使用） */
    fallbackQQAppId?: string | number;
    /** 额外 query 参数 */
    extraQuery?: Record<string, string | number>;
    /** 额外 reqData */
    extraReqData?: Record<string, any>;
}