@seayoo-web/gamer-api 1.0.0

package/types/src/event.d.ts

@@ -0,0 +1,151 @@
+import type { AutoLoginHandler } from "./utils";
+import type { NetRequestFactory } from "@seayoo-web/request";
+/** EventApi */
+export declare class EventApi {
+    private req;
+    private autoLogin;
+    private event;
+    /**
+     * 创建 EventApi 实例
+     *
+     * @param baseRequest - Gamer 通用的 request 工具实例，baseUrl 仅仅包含 endpoint + version
+     * @param autoLogin - 自动登录函数，由上层组件提供
+     */
+    constructor(baseRequest: ReturnType<NetRequestFactory>, autoLogin: AutoLoginHandler);
+    /**
+     * 设置 Event Id，以供后续 api 请求中使用
+     */
+    setEventId(event: number): this;
+    /**
+     * 获取运营活动的基础配置信息
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=wFXxtdNKPm
+     */
+    getEventConfig(): Promise<import("./event.config").EventConfig | null>;
+    /**
+     * 获取某个玩法参与用户数量
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=ejPOcWMvT1
+     */
+    getEngagementsUserCount(featureId: number): Promise<number | null>;
+    /**
+     * 获取某个玩法参与次数
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=ejPOcWMvT1
+     */
+    getEngagementsCount(featureId: number): Promise<number | null>;
+    /**
+     * 获取某个玩法的参与记录（和特定用户无关）
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=THtZ4ewIQW
+     */
+    getEngagements(featureId: number): Promise<import("./event.other").CommentEngagement[] | import("./event.other").TeamEngagement[]>;
+    /**
+     * 用户访问某个活动，需要先设置 idToken / weixinToken，返回是否
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=DWtJrnrBCn
+     */
+    userVisit(option?: {
+        feature_id?: number;
+        server_id?: string;
+        role_id?: string;
+        /** 来源标识 */
+        utm_source?: string;
+        /** 邀请人的世游通行证 ID */
+        invited_by?: string;
+    }): Promise<{
+        first_visit: boolean;
+    } | null>;
+    /**
+     * 获取用户在目标活动下的所有玩法的参与状态，用于前端进一步确定如何执行交互逻辑
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=WzX5BrMNpL
+     */
+    getUserFeatureStatus(serverId?: string, roleId?: string): Promise<import("./event.other").UserFeatureStatus[]>;
+    /**
+     * 获取当前登录用户参与某个玩法的记录
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=WSbAeDZc8F
+     */
+    getUserEngagements(featureId: number): Promise<import("./event.other").UserEngagement[]>;
+    /**
+     * 查询用户活动道具数量。注意，这里只能是活动道具
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=mnGCTeTgMb
+     */
+    getUserItemCount(itemId: number): Promise<number | null>;
+    /**
+     * 填写实物奖励收货地址
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=QIwGhnaexb
+     */
+    submitUserRewardAddress(option: {
+        reward_id: number;
+        /** ⚠️ 用户收货地址 id，后续会删除 */
+        address_id?: number;
+        /** 收件人昵称 */
+        recipient: string;
+        mobile: string;
+        province: string;
+        city: string;
+        district: string;
+        address: string;
+    }): Promise<boolean | null>;
+    /**
+     * 小程序码携带参数最多 32 个可见字符，若前端携带参数过长，则将参数保存在 api 中，并返回符合小程序码要求的 scene
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=TbEeyUmZzN
+     *
+     * @param params - 前端扫描二维码打开小程序所需参数
+     */
+    getUnlimitQrcodeScene(params: string): Promise<string | null>;
+    /**
+     * 根据小程序码携带 scene 值，获取对应的前端所需参数
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=SzWPFZDQBV
+     *
+     * @param scene - 小程序码 scene 值
+     */
+    getParamsByQrcodeScene(scene: string): Promise<string | null>;
+    /**
+     * 生成不限制的带参数的小程序码
+     *
+     * https://kdocs.cn/l/ckWFDcOsYEUA?linkname=Rvmoq8iIy0
+     */
+    generateUnlimitQrcode(option: {
+        app_id: string;
+        /**
+         * 小程序码所携带参数
+         *
+         * https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/qrcode-link/qr-code/getUnlimitedQRCode.html#%E8%AF%B7%E6%B1%82%E5%8F%82%E6%95%B0
+         */
+        scene: string;
+        page?: string;
+        /**
+         * 检查 page 是否存在；检查时小程序必须已发布，且 page 存在。
+         *
+         * 0 默认检查  1 检查  2 不检查
+         */
+        check_path?: 0 | 1 | 2;
+        /**
+         * 扫描小程序码打开的小程序版本，默认是正式版
+         *
+         * - release  正式版小程序
+         * - trial    体验版小程序
+         * - develop  开发版小程序
+         */
+        env_version?: "release" | "trial" | "develop";
+        /** 小程序码的宽度，单位：px，最小 280，最大 1280，默认 430 */
+        width?: number;
+        /** 小程序码自动配置线条颜色 */
+        auto_color?: boolean;
+        /** 小程序码线条颜色，autoColor 为 false 时生效，使用 rgb 设置颜色 */
+        line_color?: {
+            r?: string;
+            g?: string;
+            b?: string;
+        };
+        /** 生成的小程序码是否需要透明底色 */
+        is_hyaline?: boolean;
+    }): Promise<string | null>;
+}

package/types/src/event.other.d.ts

@@ -0,0 +1,151 @@
+import type { EFeatureType, EGameItemType, EQuestObjective } from "./event.config";
+export declare function isCommonCountResponse(data: unknown): data is {
+    count: number;
+};
+interface EngamentsResponse {
+    engagements: CommentEngagement[] | TeamEngagement[];
+}
+export interface CommentEngagement {
+    /** 用户世游通行证 ID */
+    user_id: string;
+    /** 用户昵称 */
+    name: string;
+    /** 用户头像地址 */
+    avatar_url: string;
+    /** 评论信息 */
+    comment: string;
+    /** 用户发布弹幕的视频点 */
+    video_note: number;
+    /** 用户发布弹幕的时间 */
+    created_at: number;
+}
+export interface TeamEngagement {
+    /** 组队码 */
+    objective: string;
+    /** 队长角色名称 */
+    leader_name: string;
+    /** 队员数量 */
+    total_members: number;
+}
+export declare function isEngamentsResponse(data: unknown): data is EngamentsResponse;
+export declare function isUserVisitResponse(data: unknown): data is {
+    first_visit: boolean;
+};
+interface UserFeatureStatusResponse {
+    status: UserFeatureStatus[];
+}
+export interface UserFeatureStatus {
+    feature_id: number;
+    can_engage: boolean;
+    has_unclaimed_rewards: boolean;
+}
+export declare function isUserFeatureStatusResponse(data: unknown): data is UserFeatureStatusResponse;
+interface UserEngagementsResponse {
+    engagements: UserEngagement[];
+}
+export declare function isUserEngagementsResponse(data: unknown): data is UserEngagementsResponse;
+export interface UserEngagement {
+    engagement_id: number;
+    sequence: number;
+    feature_id: number;
+    reward_id: number;
+    reward_status: "ineligible" | "unaccalimed" | "received";
+    reward_source: "output" | "engage";
+    data?: PreregisterEngagementData | LotteryEngagementData | SurveyEngagementData | InviteEngagementData | ShareEngagementData | VoteEngagementData | WeixinSubscribeEngagementData | CashbackEngagementData | GiftCodeEngagementData | TeamEngagementData | QuestEngagementData | LotteryDrawEngagementData;
+    server_id?: string;
+    role_id?: string;
+    created_at: number;
+}
+interface PreregisterEngagementData {
+    platforms: string[];
+}
+interface LotteryEngagementData {
+    lottery_count: number;
+}
+interface SurveyEngagementData {
+    serial_number: number;
+}
+interface InviteEngagementData {
+    user_id: string;
+    name: string;
+    avatar_url: string;
+}
+interface ShareEngagementData {
+    platform: string;
+}
+interface VoteEngagementData {
+    option_sn: string;
+}
+interface WeixinSubscribeEngagementData {
+    weixin_openid: string;
+}
+interface CashbackEngagementData {
+    order_total_amount: string | number;
+    cashback_total_amount: string | number;
+    game_item_count: string | number;
+}
+interface GiftCodeEngagementData {
+    gift_code: string;
+}
+interface TeamEngagementData {
+    team_code: string;
+    visibility: "private" | "public";
+    members: {
+        is_leader: boolean;
+        role_name: string;
+        server_name: string;
+    }[];
+}
+interface QuestEngagementData {
+    objective: EQuestObjective;
+    progress: number;
+    completion_value?: number;
+    team?: {
+        progress: number;
+        completion_value?: number;
+        players: {
+            user_id: number;
+            role_name: string;
+            is_leader: boolean;
+            progress?: number;
+        }[];
+    };
+}
+interface LotteryDrawEngagementData {
+    tickets: ({
+        ticket: string;
+        status: "unknown" | "pending";
+    } | {
+        ticket: string;
+        status: "drawn" | "claimed" | "fail";
+        reward: LotteryDrawUserReward;
+    })[];
+}
+interface LotteryDrawUserReward {
+    reward_id: number;
+    reward_item_id: number;
+    reward_item_name: string;
+    reward_source: "output" | "engage";
+    reward_item_type: EGameItemType;
+    reward_item_icon_url: string;
+    reward_item_desc?: string;
+    reward_amount: number;
+    reward_status: "unaccalimed" | "received" | "failed" | "delivered";
+    event_id: number;
+    event_name: string;
+    feature_id: number;
+    engagement_id: number;
+    feature_type: EFeatureType;
+    receive_time: number;
+    extra_data?: Record<string, unknown>;
+}
+export declare function isGetUnlimitQrcodeSceneResponse(data: unknown): data is {
+    scene: string;
+};
+export declare function isGetParamsByQrcodeSceneResponse(data: unknown): data is {
+    params: string;
+};
+export declare function isGenerateUnlimitQrcodeResponse(data: unknown): data is {
+    img: string;
+};
+export {};

package/types/src/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动登录函数(获取 Gamer Token)
+ */
+export type AutoLoginHandler = () => Promise<boolean>;
+/**
+ * 将 endpoint & verison 转成 request base url
+ */
+export declare function getBaseUrl(endpoint: string, version?: string): string;
+export declare const console: Pick<Console, "log" | "error" | "warn">;

package/types/src/weixin.guards.d.ts

@@ -0,0 +1,13 @@
+export interface WeixinLoginResponse {
+    /** 微信小程序下，用户的 openid */
+    openid: string;
+    /** 微信小程序所在的微信开放平台账号下，用户的 unionid */
+    unionid: string;
+    /**
+     * Gamer 为这个微信小程序用户签发的 Weixin Token。长期有效
+     *
+     * 对 Weixin Token 的详细描述请阅读 [世游用户运营 - JWT 场景与规范](https://365.kdocs.cn/l/cbxbzWc6zSgY)
+     */
+    weixin_token: string;
+}
+export declare function isWeixinLoginResponse(data: unknown): data is WeixinLoginResponse;

package/types/src/wexin.d.ts

@@ -0,0 +1,48 @@
+import { type AutoLoginHandler } from "./utils";
+import type { NetRequestFactory } from "@seayoo-web/request";
+export declare class WeixinApi {
+    private req;
+    private autoLogin;
+    /**
+     * 创建 WeixinApi 实例
+     *
+     * @param baseRequest - Gamer 通用的 request 工具实例，baseUrl 仅仅包含 endpoint + version
+     * @param autoLogin - 自动登录函数，由上层组件提供
+     */
+    constructor(baseRequest: ReturnType<NetRequestFactory>, autoLogin: AutoLoginHandler);
+    /**
+     * 微信静默登录，获取 weixinToken / openid / unionid，其中 weixinToken 应该被缓存
+     *
+     * 使用场景为：
+     *
+     * - 用户通过任意途径打开小程序的任意页面后，如果本地缓存中不存在微信用户身份信息，则自动调用此 API。
+     * - 调用成功后，应当使用存储能力将 response 中的微信用户身份信息缓存在本地。
+     *
+     * 小程序不应当频繁调用此 API。
+     *
+     * 由于小程序的存储是以用户维度隔离的，每个微信用户在每个小程序下只需要成功调用一次此 API。
+     *
+     * [API文档 weixin/login](https://kdocs.cn/l/cf2mO2uRLqh9?linkname=x17CeNlDQx)
+     *
+     * @param wxcode - 微信小程序调用 wx.login 获得的登录凭证
+     * @param appid - 微信小程序的 Appid，后端 api 可以从请求的 referer 中提取，后续会删除此参数
+     */
+    login(wxcode: string, appid: string): Promise<import("./weixin.guards").WeixinLoginResponse | {
+        error: string;
+        message: string;
+    }>;
+    /**
+     * 关联游戏账号
+     *
+     * 用于从游戏内跳转至小程序时，将微信用户身份和游戏内身份关联起来，使得后续的企业微信客服流程能够知道该微信用户在游戏内的身份。
+     *
+     * https://kdocs.cn/l/cf2mO2uRLqh9?linkname=ci73N833Mk
+     *
+     * @param weixinToken 调用 login 后，得到的 Weixin Token
+     * @param gameCode 从游戏内跳转至小程序时，通过请求参数 query 携带的 game_code
+     */
+    linkPlayer(weixinToken: string, gameCode: string): Promise<true | {
+        error: string;
+        message: string;
+    }>;
+}

package/types/wx.d.ts

@@ -0,0 +1,36 @@
+import { GamerBaseApi } from "./src/base";
+import { ClubApi } from "./src/club";
+import { EventApi } from "./src/event";
+import { WeixinApi } from "./src/wexin";
+export declare class GamerApi extends GamerBaseApi {
+    private weixinToken;
+    /** event api 集合 */
+    event: EventApi;
+    /** club api 集合 */
+    club: ClubApi;
+    /** weixin api 集合 */
+    weixin: WeixinApi;
+    constructor(endpoint: string, option?: {
+        version?: string;
+    });
+    /**设置 Weixin Token，用于后续请求自动置换 Gamer Token */
+    setWeixinToken(weixinToken: string): this;
+    /** 读取设置 wexinToken */
+    getWexinToken(): string;
+    /**
+     * 用世游通行证统一登录能力签发的 idToken 和 weixinToken，自动置换 gamerToken，成功后会自动设置后续 Request Headers
+     *
+     * [世游通行证统一登录](https://kdocs.cn/l/cf2mO2uRLqh9?linkname=FJXYgqvLHs)
+     *
+     * [世游通行证统一登录 - 微信小程序](https://365.kdocs.cn/l/ccHVuUs0UsZs)
+     *
+     * - 此方法通常不需要手动调用，在需要登录的接口调用时会自动执行
+     * - 为了提高页面执行速度，可以在 setIdToken + setWeixinToken 后立即调用 autoLogin，比如
+     *
+     * @example
+     * ``` js
+     *  gamerApi.setIdToken("xxxxx").setWeixinToken("yyyyyy").autoLogin()
+     * ```
+     */
+    autoLogin(): Promise<boolean>;
+}