@seayoo-web/gamer-api 1.0.0 → 1.0.3

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

@@ -0,0 +1,169 @@
+/** 道具类型 */
+export declare const enum GamerItemType {
+    /** 活动道具 */
+    EventItem = "event_item",
+    /** 游戏内道具 */
+    GameItem = "game_item",
+    /** 实物 */
+    PhysicalItem = "physical_item",
+    /** 微信红包 */
+    WeixinHongbao = "weixin_hongbao",
+    /** 礼包码 */
+    GiftCode = "gift_code",
+    /** 抽奖券 */
+    LotteryTicket = "lottery_ticket",
+    /** 空奖励 */
+    VoidItem = "void_item"
+}
+/** 参与活动的账号类型 */
+export declare const enum EngageAccountType {
+    /** 世游通行证 ID / Combo ID */
+    UserId = "user_id",
+    /** 游戏角色 ID */
+    RoleId = "role_id"
+}
+/** 玩法刷新周期类型 */
+export declare const enum EventPeriodType {
+    None = "none",
+    Daily = "daily",
+    Weekly = "weekly",
+    Monthly = "monthly"
+}
+/** 活动玩法类型 */
+export declare const enum FeatureType {
+    /** 预约 */
+    Preregister = "preregister",
+    /** 抽奖 */
+    Lottery = "lottery",
+    /** 问卷 */
+    Survey = "survey",
+    /** 邀请 */
+    Invite = "invite",
+    /** 分享 */
+    Share = "share",
+    /** 关注社交媒体 */
+    Follow = "follow",
+    /** 微信小程序订阅消息 */
+    Subscribe = "weixin_subscribe",
+    /** 弹幕/评论 */
+    Comment = "comment",
+    /** 投票 */
+    Vote = "vote",
+    /** 礼包码 */
+    GiftCode = "gift_code",
+    /** 注册 */
+    Register = "register",
+    /** 受邀注册 */
+    InvitedRegister = "invited_register",
+    /** 领奖 */
+    ClaimRewards = "claim_rewards",
+    /** 充值返还 */
+    Cashback = "cashback",
+    /** 任务 */
+    Quest = "quest",
+    /** 组队 */
+    Team = "team",
+    /** 开奖 */
+    LotteryDraw = "lottery_draw"
+}
+/** 任务玩法的目标类型 */
+export declare const enum QuestObjective {
+    /** 累计游戏内活跃值 */
+    Active = "player_active_points",
+    /** 累计登录，单位 人天 */
+    Login = "player_login_days",
+    /** 累计充值金额 */
+    OrderAmount = "order_total_amount",
+    /** 社区发帖数量 */
+    Posts = "community_posts",
+    /** 社区评论数量 */
+    Comments = "community_comments"
+}
+/** 投票数据来源 */
+export declare const enum VoteOptionSource {
+    /** 官方上传 */
+    System = "system",
+    /** 用户投稿 */
+    UserSubmission = "user_submission",
+    /** 投票入围 */
+    Shortlisted = "shortlisted"
+}
+/** 奖励领取状态(不含发货状态和领取失败) */
+export declare const enum RewardStatusPrefix {
+    /** 未获得奖励 */
+    Ineligible = "ineligible",
+    /** 奖励未领取 */
+    Unaccalimed = "unaccalimed",
+    /** 奖励已领取 */
+    Received = "received"
+}
+/** 已获得实物奖励的奖励状态 */
+export declare const enum RewardStatusSuffix {
+    /** 奖励未领取 */
+    Unaccalimed = "unaccalimed",
+    /** 奖励已领取 */
+    Received = "received",
+    /** 奖励发放失败 */
+    Failed = "failed",
+    /** 奖励已发货 */
+    Delivered = "delivered"
+}
+export declare const enum CliamRewardStatus {
+    /** 未获得奖励 */
+    Ineligible = "ineligible",
+    /** 奖励未领取 */
+    Unaccalimed = "unaccalimed",
+    /** 奖励已领取 */
+    Received = "received",
+    /** 奖励发放失败 */
+    Failed = "failed"
+}
+/** 奖励来源 */
+export declare const enum RewardSoure {
+    /** 玩法产出奖励 */
+    Output = "output",
+    /** 玩法参与奖励 */
+    Engage = "engage"
+}
+/** 组队玩法中队伍的可见性 */
+export declare const enum TeamVisibility {
+    /** 私有队伍 */
+    Private = "private",
+    /** 公开队伍 */
+    Public = "public"
+}
+/** 抽奖券状态 */
+export declare const enum LotteryTicketStatus {
+    /** 未知状态 */
+    Unknown = "unknown",
+    /** 等待开奖 */
+    Pending = "pending",
+    /** 已开奖，待领奖 */
+    Drawn = "drawn",
+    /** 已领奖 */
+    Claimed = "claimed",
+    /** 领奖失败 */
+    Fail = "fail"
+}
+/** 组队玩法队伍操作类型 */
+export declare const enum TeamAction {
+    /** 发起组队 */
+    Assemble = "assemble",
+    /** 加入队伍 */
+    Join = "join",
+    /** 解散队伍 */
+    Disband = "disband",
+    /** 修改队伍可见性 */
+    ChangeVisibility = "change_visibility",
+    /** 查询组队信息 */
+    Query = "query"
+}
+/** 抽奖券玩法操作类型 */
+export declare const enum LotteryDrawAction {
+    /** 查询抽奖券 */
+    Query = "query",
+    /** 开奖 */
+    Draw = "draw",
+    /** 领奖 */
+    Claim = "claim"
+}

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

@@ -0,0 +1,37 @@
+import type { ClaimedItem, CommentEngagement, EngageResponse, TeamEngagement, UserEngagement, UserFeatureStatus, UserReward, VerifyMobileResult } from "./event.define";
+import type { CliamRewardStatus } from "./event.enums";
+export declare function isVerifyMobileResponse(data: unknown): data is VerifyMobileResult;
+export declare function isCommonCountResponse(data: unknown): data is {
+    count: number;
+};
+export declare function isEngamentsResponse(data: unknown): data is {
+    engagements: CommentEngagement[] | TeamEngagement[];
+};
+export declare function isUserVisitResponse(data: unknown): data is {
+    first_visit: boolean;
+};
+export declare function isUserFeatureStatusResponse(data: unknown): data is {
+    status: UserFeatureStatus[];
+};
+export declare function isUserEngagementsResponse(data: unknown): data is {
+    engagements: UserEngagement[];
+};
+export declare function isEngageResponse(data: unknown): data is EngageResponse;
+export declare function isClaimRewardsResponse(data: unknown): data is {
+    claimed_items: ClaimedItem[];
+};
+export declare function isClaimWeixinHongbaoResponse(data: unknown): data is {
+    reward_status: CliamRewardStatus;
+};
+export declare function isGetUserRewardsResponse(data: unknown): data is {
+    user_rewards: UserReward[];
+};
+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;
+};

package/types/src/token.d.ts

@@ -0,0 +1,82 @@
+import type { StorageHelper } from "./token.define";
+import type { NetRequestFactory } from "@seayoo-web/request";
+export * from "./token.define";
+/**
+ * auth 管理工具 + request 工具
+ *
+ * 核心概念如下：
+ *
+ * - [ID Token](https://365.kdocs.cn/l/ctrXywvA1Wfd)
+ * - [Gamer Token](https://365.kdocs.cn/l/crZwOsI54RBH)
+ * - [Weixin Token](https://kdocs.cn/l/cf2mO2uRLqh9?linkname=YtzQpmRQ0v)
+ */
+export declare class AuthToken {
+    private $idToken;
+    private $weixinToken;
+    private $gamerToken;
+    private inWxMiniProgram;
+    req: ReturnType<NetRequestFactory>;
+    storage: StorageHelper;
+    constructor({ endpoint, NetRequest, storage, }: {
+        /**
+         * 服务端点
+         *
+         * https://kdocs.cn/l/cf2mO2uRLqh9?linkname=k2iGGXbfov
+         */
+        endpoint: string;
+        /** request 工具 */
+        NetRequest: NetRequestFactory;
+        /** 本地存储服务 */
+        storage: StorageHelper;
+    });
+    /** 当前是否为登录状态，即是否拥有 gamerToken */
+    get isLogined(): boolean;
+    /** 读取已经设置的 idToken */
+    get idToken(): string;
+    /** 设置从登录组件获取的 Id Token，用于后续请求自动置换 Gamer Token */
+    set idToken(value: string);
+    /** 读取设置 wexinToken */
+    get weixinToken(): string;
+    /**
+     * 设置 Weixin Token，用于后续请求自动置换 Gamer Token
+     *
+     * 仅仅在微信小程序模式下有效
+     */
+    set weixinToken(value: string);
+    /** 读取自动置换的 gamerToken */
+    get gamerToken(): string;
+    /** 直接写入 Gamer Token，通常在 ComboWebView 中读取 url 中的 gamer_token 传入 */
+    set gamerToken(value: string);
+    /**
+     * 用世游通行证统一登录能力签发的 ID Token / Weixin Token，自动置换 Gamer Token，成功后会自动设置后续 Request Headers
+     *
+     * [世游通行证统一登录](https://kdocs.cn/l/cf2mO2uRLqh9?linkname=FJXYgqvLHs)
+     *
+     * [世游通行证统一登录 - Web 站点](https://365.kdocs.cn/l/cf57sp1qLlZh)
+     *
+     * [世游通行证统一登录 - 微信小程序](https://365.kdocs.cn/l/ccHVuUs0UsZs)
+     *
+     * - 此方法通常不需要手动调用，在需要登录的接口调用时会自动执行
+     * - 为了提高页面执行速度，可以在设置 Token 后立即调用 autoLogin
+     */
+    autoLogin(): Promise<boolean>;
+    /**
+     * 获取当前 Session 的信息
+     *
+     * https://kdocs.cn/l/cf2mO2uRLqh9?linkname=OdGVCdQxEu
+     */
+    getSession(): Promise<import("./token.define").GamerSession | null>;
+    /**
+     * 实名认证
+     *
+     * https://kdocs.cn/l/cf2mO2uRLqh9?linkname=kZYnwX6RcF
+     */
+    authRealName(option: {
+        /** 用户输入的真实姓名。明文或者密文 */
+        real_name: string;
+        /** 用户输入的身份证号码。明文或者密文 */
+        identity_card: string;
+        /** 预留参数，是否加密 real_name 和 identity_card，加密的密钥应当使用 api 服务的 ECDSA Public Key */
+        encrypted?: boolean;
+    }): Promise<import("./token.define").GamerSession | null>;
+}

package/types/src/token.define.d.ts

@@ -0,0 +1,29 @@
+export type PopupFn = (option: {
+    title?: string;
+    content: string;
+    cancelText?: string;
+    confirmText: string;
+    onCancel?: () => void;
+    onConfirm: () => void;
+}) => void;
+export type ToastFn = (content: string, timeout?: number) => void;
+export type StorageHelper = {
+    set(key: string, value: string): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+};
+export interface GamerSession {
+    /** 世游通行证 ID */
+    seayoo_user_id?: string;
+    /** 手机号码（掩码形式） */
+    seayoo_mobile?: string;
+    /** 世游通行证用户实名信息（掩码形式） */
+    seayoo_real_name?: string;
+    /** Combo ID */
+    combo_id?: string;
+    /**
+     * combo_id 背后的 IdP
+     *
+     * 取值参见 [Combo Client REST API 中的 idp](https://kdocs.cn/l/cg0cfHzazsta?linkname=ZVDdf1pe48)，仅当 combo_id 有值时才有值
+     */
+    combo_idp?: string;
+}

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

@@ -0,0 +1,5 @@
+import type { GamerSession } from "./token.define";
+export declare function isGamerTokenResponse(data: unknown): data is {
+    gamer_token: string;
+};
+export declare function isGetSessionResponse(data: unknown): data is GamerSession;

package/types/src/utils.d.ts

@@ -1,9 +1,5 @@
-/**
- * 自动登录函数(获取 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">;
+/** 检测是否在 combo webview */
+export declare function inComboWebview(): boolean;
+/** 检测是否为微信小程序环境 */
+export declare function isWeixinMiniProgram(): boolean;

package/types/src/weixin.d.ts

@@ -0,0 +1,83 @@
+import type { AuthToken } from "./token";
+import type { WeixinWebLoginErrorCode } from "./weixin.define";
+import type { RequestInteralError } from "@seayoo-web/request";
+export * from "./weixin.define";
+export declare class WeixinApi {
+    private token;
+    private appid;
+    private req;
+    /**
+     * 创建微信相关功能接口
+     *
+     * - authToken 需要导入 AuthToken 进行初始化后传入
+     * - appid 可以静态设置，也可以在小程序中动态获取，见下示例代码
+     *
+     * ```js
+     * const info = wx.getAccountInfoSync();
+     * console.log(info.miniProgram.appId)
+     * ```
+     *
+     * https://developers.weixin.qq.com/miniprogram/dev/api/open-api/account-info/wx.getAccountInfoSync.html
+     */
+    constructor(authToken: AuthToken, appid: string);
+    /**
+     * 检查缓存中的登录数据
+     *
+     * 如果没有缓存或缓存数据错误，则需要调用 [wx.login](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html) 后调用 login 方法
+     *
+     * 也可以直接调用 login 方法，并传入 wxcode 的读取函数
+     */
+    getLoginCache(): Promise<import("./weixin.define").WeixinLoginResponse | null>;
+    /**
+     * 小程序页面微信静默登录，获取 weixinToken / openid / unionid。
+     *
+     * 使用场景：
+     *
+     * - 小程序的任意页面打开后应该优先调用此方法以获取登录状态
+     *
+     * 注意：
+     *
+     * - 登录成功后会将登录信息缓存到本地，重复或并发调用不会引起任何副作用。
+     * - 由于小程序的存储是以用户维度隔离的，每个微信用户在每个小程序下只要成功调用一次此 API 就会缓存请求结果。
+     * - 微信公众号网页授权请使用 webLogin 方法
+     *
+     * https://kdocs.cn/l/cf2mO2uRLqh9?linkname=GwIZ0givCb
+     *
+     * @param wxLoginCodeGetter - 微信小程序调用 [wx.login](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html) 获得的登录凭证
+     */
+    login(wxLoginCodeGetter: () => Promise<string>): Promise<import("./weixin.define").WeixinLoginResponse | {
+        error: RequestInteralError | "invalid_weixin_appid" | "invalid_weixin_code";
+    }>;
+    /**
+     * 在微信内嵌网页中调用微信公众号授权登录【暂未启用】
+     *
+     * 注意：
+     *
+     * - 登录回调地址强制是当前页面，包括 location search 和 location hash 部分
+     * - 登录跳转返回 code 后，会将 code 从 url 中删除以防止 code 泄露，如需设置分享则需要在此方法执行完毕之后
+     *
+     * 官方参考资料：
+     *
+     * - [微信网页开发 / 网页授权](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html)
+     *
+     * @param scope - 网页授权作用域
+     *  - snsapi_base 不弹出授权页面，用户无感知，只能获取用户 openid，如果需要获取 unionid 则需要 snsapi_userinfo
+     *  - snsapi_userinfo 【默认】弹出授权页面，可拿到 openid、unionid、昵称、头像等信息，但用户也可能会拒绝授权
+     */
+    webLogin(scope?: "snsapi_base" | "snsapi_userinfo"): Promise<import("./weixin.define").WeixinLoginResponse | {
+        error: WeixinWebLoginErrorCode;
+    } | {
+        error: RequestInteralError | "invalid_weixin_appid" | "invalid_weixin_code";
+    } | undefined>;
+    /**
+     * 关联游戏账号，无返回值，全程静默
+     *
+     * 用于从游戏内跳转至小程序时，将微信用户身份和游戏内身份关联起来，使得后续的企业微信客服流程能够知道该微信用户在游戏内的身份。
+     *
+     * https://kdocs.cn/l/cf2mO2uRLqh9?linkname=ci73N833Mk
+     *
+     * @param weixinToken 调用 login 后，得到的 weixinToken，如果 weixinToken 为空则跳过不处理
+     * @param gameCode 从游戏内跳转至小程序时，通过请求参数 query 携带的 game_code，如果值为空则跳过不处理
+     */
+    linkPlayer(weixinToken: string, gameCode: string): Promise<void>;
+}

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

@@ -0,0 +1,41 @@
+export interface WeixinLoginResponse {
+    /** 微信小程序下，用户的 openid */
+    openid: string;
+    /** 微信小程序所在的微信开放平台账号下，用户的 unionid */
+    unionid: string;
+    /**
+     * Gamer 为这个微信小程序用户签发的 Weixin Token。长期有效
+     *
+     * 对 Weixin Token 的详细描述请阅读 [世游用户运营 - JWT 场景与规范](https://365.kdocs.cn/l/cbxbzWc6zSgY)
+     */
+    weixin_token: string;
+}
+/**
+ * 微信web登录错误码
+ *
+ * https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html
+ */
+export declare const enum WeixinWebLoginErrorCode {
+    /** redirect_uri域名与后台配置不一致 */
+    RedirectUriDisMatch = "10003",
+    /** 不支持微信开放平台的 Appid，请使用公众号Appid */
+    AppidError = "10016",
+    /** 公众号未授权第三方平台，请检查授权状态 */
+    AuthorizationError = "10015",
+    /** 此公众号并没有这些 scope 的权限 */
+    NoRightForScope = "10005",
+    /** 操作太频繁了，请稍后重试 */
+    Frequently = "10009",
+    /** 此公众号被封禁 */
+    AppBanded = "10004",
+    /** 必须关注此测试号 */
+    ShouldFllow = "10006",
+    /** scope不能为空 */
+    ScopeNull = "10010",
+    /** redirect_uri不能为空 */
+    RedirectUriNull = "10011",
+    /** appid不能为空 */
+    AppidNull = "10012",
+    /** state不能为空 */
+    StateNull = "10013"
+}

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

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