lxns-rhythm-api 0.1.9 → 0.1.10

package/README.md

@@ -72,6 +72,45 @@ const jacket = await client.maimai.getAsset("jacket", 114);
 const icon = await client.chunithm.getAsset("icon", 1);
 ```
 
+## OAuth 流程
+
+```ts
+import { LxnsOAuthClient } from "lxns-rhythm-api";
+
+const client = new LxnsOAuthClient({
+  clientId: "<your-client-id>",
+  redirectURI: "https://example.com/callback",
+  clientSecret: "<your-client-secret>", // PKCE 可不传
+});
+
+// 1) 生成授权链接，跳转给用户
+const authorizeURL = client.createAuthorizeURL({
+  scope: ["read_user_profile", "read_player"],
+  state: "nonce", // 可选
+  codeChallenge: "<code-challenge>", // PKCE 可选
+  codeChallengeMethod: "S256",
+});
+
+// 2) 回调拿到 code 后换 token
+const token = await client.exchangeCodeForToken({
+  code: "<auth-code>",
+  codeVerifier: "<code-verifier>", // PKCE 模式传这个
+});
+
+// 3) 用 access_token 创建授权态客户端
+const authorized = client.createAuthorizedClient(token.access_token);
+
+// 4) 调用 OAuth 用户接口和 personal 接口
+const profile = await authorized.user.getProfile();
+const maimaiPlayer = await authorized.maimai.getPlayer();
+const chunithmPlayer = await authorized.chunithm.getPlayer();
+
+// 5) 刷新 token
+const nextToken = await client.refreshAccessToken({
+  refreshToken: token.refresh_token,
+});
+```
+
 ## 错误处理
 
 SDK 会将 API 错误统一抛为 `LxnsApiError`。
@@ -112,6 +151,7 @@ try {
 ```ts
 import {
   LxnsApiClient,
+  LxnsOAuthClient,
   LxnsApiError,
   isLxnsApiError,
   MaimaiModels,
@@ -123,6 +163,8 @@ import {
 
 - [Lxns maimai API](https://maimai.lxns.net/docs/api/maimai)
 - [Lxns chunithm API](https://maimai.lxns.net/docs/api/chunithm)
+- [Lxns OAuth API](https://maimai.lxns.net/docs/api/oauth)
+- [Lxns OAuth 接入指南](https://maimai.lxns.net/docs/oauth-guide)
 
 ## 构建与测试
 

package/dist/index.cjs

@@ -23,7 +23,10 @@ __export(index_exports, {
   ChunithmModels: () => models_exports,
   LxnsApiClient: () => LxnsApiClient,
   LxnsApiError: () => LxnsApiError,
+  LxnsOAuthClient: () => LxnsOAuthClient,
   MaimaiModels: () => models_exports2,
+  OAuthAuthorizedApi: () => OAuthAuthorizedApi,
+  OAuthUserApi: () => OAuthUserApi,
   isAuthError: () => isAuthError,
   isLxnsApiError: () => isLxnsApiError,
   isNotFoundError: () => isNotFoundError,
@@ -61,6 +64,106 @@ var LevelIndex2 = /* @__PURE__ */ ((LevelIndex3) => {
   return LevelIndex3;
 })(LevelIndex2 || {});
 
+// src/api/chunithm/personal-api.ts
+var ChunithmPersonalApi = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 获取玩家信息
+   * GET /api/v0/user/chunithm/player
+   */
+  async getPlayer() {
+    return this.http.get("player").json();
+  }
+  /**
+   * 获取玩家所有成绩
+   * GET /api/v0/user/chunithm/player/scores
+   */
+  async getScores() {
+    return this.http.get("scores").json();
+  }
+  /**
+   * 上传玩家成绩
+   * POST /api/v0/user/chunithm/player/scores
+   */
+  async postScores(scores) {
+    const body = { scores };
+    return this.http.post("scores", { json: body }).json();
+  }
+};
+
+// src/api/maimai/personal-api.ts
+var MaimaiPersonalApi = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 获取玩家信息
+   * GET /api/v0/user/maimai/player
+   * @returns PlayerInfo
+   */
+  async getPlayer() {
+    return this.http.get("player").json();
+  }
+  /**
+   * 获取玩家所有成绩
+   * GET /api/v0/user/maimai/player/scores
+   * @returns PlayerScores
+   */
+  async getScores() {
+    return this.http.get("scores").json();
+  }
+  /**
+   * 上传玩家成绩
+   * POST /api/v0/user/maimai/player/scores
+   * @param scores 成绩列表
+   * @returns 上传结果
+   */
+  async postScores(scores) {
+    const body = { scores };
+    return this.http.post("scores", { json: body }).json();
+  }
+};
+
+// src/api/oauth/user.ts
+var OAuthUserApi = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 获取用户基本信息
+   * GET /api/v0/user/profile
+   * @returns 用户基本信息
+   */
+  async getProfile() {
+    return this.http.get("profile").json();
+  }
+  /**
+   * 获取用户个人 API 密钥
+   * GET /api/v0/user/token
+   * @returns 用户个人 API 密钥
+   */
+  async getToken() {
+    return this.http.get("token").json();
+  }
+};
+
+// src/api/oauth/oauth.ts
+var OAuthAuthorizedApi = class {
+  /** GET /api/v0/user/profile 与 GET /api/v0/user/token */
+  user;
+  /** OAuth 授权后可访问的 maimai personal API */
+  maimai;
+  /** OAuth 授权后可访问的 chunithm personal API */
+  chunithm;
+  constructor(userHttp, maimaiHttp, chunithmHttp) {
+    this.user = new OAuthUserApi(userHttp);
+    this.maimai = new MaimaiPersonalApi(maimaiHttp);
+    this.chunithm = new ChunithmPersonalApi(chunithmHttp);
+  }
+};
+
 // node_modules/.pnpm/ky@1.10.0/node_modules/ky/distribution/errors/HTTPError.js
 var HTTPError = class extends Error {
   response;
@@ -683,7 +786,7 @@ var createInstance = (defaults) => {
 var ky = createInstance();
 var distribution_default = ky;
 
-// src/api/chunithm/dev.ts
+// src/api/chunithm/dev-api.ts
 var ChunithmDevApi = class {
   constructor(http) {
     this.http = http;
@@ -783,36 +886,7 @@ var ChunithmDevApi = class {
   }
 };
 
-// src/api/chunithm/personal.ts
-var ChunithmPersonalApi = class {
-  constructor(http) {
-    this.http = http;
-  }
-  /**
-   * 获取玩家信息
-   * GET /api/v0/user/chunithm/player
-   */
-  async getPlayer() {
-    return this.http.get("player").json();
-  }
-  /**
-   * 获取玩家所有成绩
-   * GET /api/v0/user/chunithm/player/scores
-   */
-  async getScores() {
-    return this.http.get("scores").json();
-  }
-  /**
-   * 上传玩家成绩
-   * POST /api/v0/user/chunithm/player/scores
-   */
-  async postScores(scores) {
-    const body = { scores };
-    return this.http.post("scores", { json: body }).json();
-  }
-};
-
-// src/api/chunithm/public.ts
+// src/api/chunithm/public-api.ts
 var ChunithmPublicApi = class {
   constructor(http) {
     this.http = http;
@@ -855,7 +929,7 @@ var ChunithmPublicApi = class {
   }
 };
 
-// src/api/maimai/dev.ts
+// src/api/maimai/dev-api.ts
 var MaimaiDevApi = class {
   constructor(http) {
     this.http = http;
@@ -974,39 +1048,6 @@ var MaimaiDevApi = class {
   }
 };
 
-// src/api/maimai/personal.ts
-var MaimaiPersonalApi = class {
-  constructor(http) {
-    this.http = http;
-  }
-  /**
-   * 获取玩家信息
-   * GET /api/v0/user/maimai/player
-   * @returns PlayerInfo
-   */
-  async getPlayer() {
-    return this.http.get("player").json();
-  }
-  /**
-   * 获取玩家所有成绩
-   * GET /api/v0/user/maimai/player/scores
-   * @returns PlayerScores
-   */
-  async getScores() {
-    return this.http.get("scores").json();
-  }
-  /**
-   * 上传玩家成绩
-   * POST /api/v0/user/maimai/player/scores
-   * @param scores 成绩列表
-   * @returns 上传结果
-   */
-  async postScores(scores) {
-    const body = { scores };
-    return this.http.post("scores", { json: body }).json();
-  }
-};
-
 // src/api/maimai/entities/song.ts
 var LevelArray = [
   "basic",
@@ -1067,7 +1108,7 @@ var Song = class {
   }
 };
 
-// src/api/maimai/public.ts
+// src/api/maimai/public-api.ts
 var MaimaiPublicApi = class {
   constructor(http) {
     this.http = http;
@@ -1175,7 +1216,7 @@ function isServerError(error) {
   return typeof code === "number" && code >= 500;
 }
 
-// src/client/lxns-api-client.ts
+// src/client/http-options.ts
 function parseLxnsJson(text) {
   const payload = JSON.parse(text);
   if (payload.success === false) {
@@ -1212,7 +1253,16 @@ async function wrapKyError(error) {
     status
   );
 }
-var LxnsApiClient = class _LxnsApiClient {
+var LXNS_HTTP_OPTIONS = {
+  parseJson: parseLxnsJson,
+  throwHttpErrors: true,
+  hooks: {
+    beforeError: [wrapKyError]
+  }
+};
+
+// src/client/lxns-api-client.ts
+var LxnsApiClient = class {
   config;
   /**
    * maimai API
@@ -1222,13 +1272,6 @@ var LxnsApiClient = class _LxnsApiClient {
    * chunithm API
    */
   chunithm;
-  static BASE_OPTIONS = {
-    parseJson: parseLxnsJson,
-    throwHttpErrors: true,
-    hooks: {
-      beforeError: [wrapKyError]
-    }
-  };
   mountGameApi({
     public: publicApi,
     dev,
@@ -1255,21 +1298,21 @@ var LxnsApiClient = class _LxnsApiClient {
     const { baseURL, devAccessToken, personalAccessToken } = this.config;
     const maimaiHttpPublic = distribution_default.create({
       prefixUrl: new URL("maimai/", baseURL),
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     });
     const maimaiHttpDev = devAccessToken ? distribution_default.create({
       prefixUrl: new URL("maimai/", baseURL),
       headers: {
         Authorization: devAccessToken
       },
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     }) : void 0;
     const maimaiHttpPersonal = personalAccessToken ? distribution_default.create({
       prefixUrl: new URL("user/maimai/", baseURL),
       headers: {
         "X-User-Token": personalAccessToken
       },
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     }) : void 0;
     this.maimai = this.mountGameApi({
       public: new MaimaiPublicApi(maimaiHttpPublic),
@@ -1287,21 +1330,21 @@ var LxnsApiClient = class _LxnsApiClient {
     });
     const chunithmHttpPublic = distribution_default.create({
       prefixUrl: new URL("chunithm/", baseURL),
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     });
     const chunithmHttpDev = devAccessToken ? distribution_default.create({
       prefixUrl: new URL("chunithm/", baseURL),
       headers: {
         Authorization: devAccessToken
       },
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     }) : void 0;
     const chunithmHttpPersonal = personalAccessToken ? distribution_default.create({
       prefixUrl: new URL("user/chunithm/", baseURL),
       headers: {
         "X-User-Token": personalAccessToken
       },
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     }) : void 0;
     this.chunithm = this.mountGameApi({
       public: new ChunithmPublicApi(chunithmHttpPublic),
@@ -1317,12 +1360,141 @@ var LxnsApiClient = class _LxnsApiClient {
     });
   }
 };
+
+// src/client/lxns-oauth-client.ts
+var LxnsOAuthClient = class {
+  /** 当前 OAuth 客户端配置 */
+  config;
+  http;
+  /**
+   * @param config OAuth 配置
+   */
+  constructor(config) {
+    this.config = {
+      ...config,
+      baseURL: config.baseURL ?? "https://maimai.lxns.net/api/v0/"
+    };
+    this.http = distribution_default.create({
+      prefixUrl: new URL("oauth/", this.config.baseURL),
+      ...LXNS_HTTP_OPTIONS
+    });
+  }
+  /**
+   * 生成 OAuth 授权链接（/oauth/authorize）。
+   * @returns 可直接跳转的授权 URL
+   */
+  createAuthorizeURL({
+    scope,
+    state,
+    codeChallenge,
+    codeChallengeMethod
+  }) {
+    const url = new URL("/oauth/authorize", this.config.baseURL);
+    const search = new URLSearchParams({
+      response_type: "code",
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectURI,
+      scope: Array.isArray(scope) ? scope.join(" ") : scope
+    });
+    if (state) {
+      search.set("state", state);
+    }
+    if (codeChallenge) {
+      search.set("code_challenge", codeChallenge);
+    }
+    if (codeChallengeMethod) {
+      search.set("code_challenge_method", codeChallengeMethod);
+    }
+    url.search = search.toString();
+    return url.toString();
+  }
+  /**
+   * 使用授权码换取访问令牌（grant_type=authorization_code）。
+   * - 机密客户端：依赖 constructor 传入的 clientSecret
+   * - PKCE 客户端：通过 codeVerifier 交换
+   */
+  async exchangeCodeForToken({ code, codeVerifier }) {
+    const payload = codeVerifier ? {
+      client_id: this.config.clientId,
+      code,
+      redirect_uri: this.config.redirectURI,
+      code_verifier: codeVerifier
+    } : {
+      client_id: this.config.clientId,
+      code,
+      redirect_uri: this.config.redirectURI,
+      client_secret: this.config.clientSecret ?? ""
+    };
+    if (!codeVerifier && !this.config.clientSecret) {
+      throw new Error(
+        "clientSecret is required when codeVerifier is not provided."
+      );
+    }
+    return this.http.post("token", {
+      json: {
+        ...payload,
+        grant_type: "authorization_code"
+      }
+    }).json();
+  }
+  /**
+   * 使用 refresh_token 刷新访问令牌（grant_type=refresh_token）。
+   */
+  async refreshAccessToken({ refreshToken }) {
+    const payload = {
+      client_id: this.config.clientId,
+      refresh_token: refreshToken,
+      client_secret: this.config.clientSecret
+    };
+    return this.http.post("token", {
+      json: {
+        ...payload,
+        grant_type: "refresh_token"
+      }
+    }).json();
+  }
+  /**
+   * 基于 access_token 创建授权态 API 客户端。
+   */
+  createAuthorizedClient(accessToken) {
+    const authorization = `Bearer ${accessToken}`;
+    const userHttp = distribution_default.create({
+      prefixUrl: new URL("user/", this.config.baseURL),
+      headers: {
+        Authorization: authorization
+      },
+      ...LXNS_HTTP_OPTIONS
+    });
+    const maimaiPersonalHttp = distribution_default.create({
+      prefixUrl: new URL("user/maimai/", this.config.baseURL),
+      headers: {
+        Authorization: authorization
+      },
+      ...LXNS_HTTP_OPTIONS
+    });
+    const chunithmPersonalHttp = distribution_default.create({
+      prefixUrl: new URL("user/chunithm/", this.config.baseURL),
+      headers: {
+        Authorization: authorization
+      },
+      ...LXNS_HTTP_OPTIONS
+    });
+    return new OAuthAuthorizedApi(
+      userHttp,
+      maimaiPersonalHttp,
+      chunithmPersonalHttp
+    );
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ChunithmModels,
   LxnsApiClient,
   LxnsApiError,
+  LxnsOAuthClient,
   MaimaiModels,
+  OAuthAuthorizedApi,
+  OAuthUserApi,
   isAuthError,
   isLxnsApiError,
   isNotFoundError,

package/dist/index.d.ts

@@ -456,6 +456,164 @@ declare namespace models {
   export { type models_Alias as Alias, type models_AssetType as AssetType, type models_BuddyNotes as BuddyNotes, type models_Collection as Collection, type models_CollectionGenre as CollectionGenre, type models_CollectionRequired as CollectionRequired, type models_CollectionRequiredSong as CollectionRequiredSong, type models_FCType as FCType, type models_FSType as FSType, type models_Frame as Frame, type models_Genre as Genre, type models_Icon as Icon, models_LevelIndex as LevelIndex, type models_NamePlate as NamePlate, type models_Notes as Notes, type models_Player as Player, type models_RateType as RateType, type models_RatingTrend as RatingTrend, type models_Score as Score, type models_SimpleScore as SimpleScore, type Song$1 as Song, type models_SongDifficulties as SongDifficulties, type models_SongDifficulty as SongDifficulty, type models_SongDifficultyUtage as SongDifficultyUtage, type models_SongType as SongType, type models_Trophy as Trophy, type models_Version as Version };
 }
 
+type PlayerScores$1 = Score$1[];
+
+/**
+ * chunithm 个人 API（需用户身份）
+ */
+declare class ChunithmPersonalApi {
+    readonly http: KyInstance;
+    constructor(http: KyInstance);
+    /**
+     * 获取玩家信息
+     * GET /api/v0/user/chunithm/player
+     */
+    getPlayer(): Promise<Player$1>;
+    /**
+     * 获取玩家所有成绩
+     * GET /api/v0/user/chunithm/player/scores
+     */
+    getScores(): Promise<PlayerScores$1>;
+    /**
+     * 上传玩家成绩
+     * POST /api/v0/user/chunithm/player/scores
+     */
+    postScores(scores: Score$1[]): Promise<unknown>;
+}
+
+type PlayerScores = Score[];
+
+/**
+ * maimai 个人 API（需用户身份，路径遵循文档）
+ */
+declare class MaimaiPersonalApi {
+    readonly http: KyInstance;
+    constructor(http: KyInstance);
+    /**
+     * 获取玩家信息
+     * GET /api/v0/user/maimai/player
+     * @returns PlayerInfo
+     */
+    getPlayer(): Promise<Player>;
+    /**
+     * 获取玩家所有成绩
+     * GET /api/v0/user/maimai/player/scores
+     * @returns PlayerScores
+     */
+    getScores(): Promise<PlayerScores>;
+    /**
+     * 上传玩家成绩
+     * POST /api/v0/user/maimai/player/scores
+     * @param scores 成绩列表
+     * @returns 上传结果
+     */
+    postScores(scores: Score[]): Promise<unknown>;
+}
+
+interface OAuthUserProfile {
+    /** 用户 ID */
+    id: number;
+    /** 用户名 */
+    username: string;
+    /** 昵称 */
+    nickname: string;
+    /** 头像 URL */
+    avatar: string;
+    /** 账号角色 */
+    role: string;
+    /** 地区 */
+    region: string;
+}
+interface OAuthUserToken {
+    /** 用户的个人 API 密钥 */
+    token: string;
+}
+/**
+ * OAuth 用户 API
+ */
+declare class OAuthUserApi {
+    readonly http: KyInstance;
+    constructor(http: KyInstance);
+    /**
+     * 获取用户基本信息
+     * GET /api/v0/user/profile
+     * @returns 用户基本信息
+     */
+    getProfile(): Promise<OAuthUserProfile>;
+    /**
+     * 获取用户个人 API 密钥
+     * GET /api/v0/user/token
+     * @returns 用户个人 API 密钥
+     */
+    getToken(): Promise<OAuthUserToken>;
+}
+
+type OAuthAuthorizeCodeTokenRequest = {
+    client_id: string;
+    code: string;
+    redirect_uri: string;
+    client_secret: string;
+    code_verifier?: never;
+} | {
+    client_id: string;
+    code: string;
+    redirect_uri: string;
+    code_verifier: string;
+    client_secret?: never;
+};
+interface OAuthRefreshTokenRequest {
+    /** OAuth 应用 ID */
+    client_id: string;
+    /** refresh_token */
+    refresh_token: string;
+    /** 机密客户端可传，PKCE 可省略 */
+    client_secret?: string;
+}
+interface OAuthTokenResponse {
+    /** 访问令牌 */
+    access_token: string;
+    /** 令牌类型（通常为 Bearer） */
+    token_type: string;
+    /** access_token 过期时间（秒） */
+    expires_in: number;
+    /** 刷新令牌 */
+    refresh_token: string;
+    /** 授权范围（空格分隔） */
+    scope: string;
+}
+interface OAuthAuthorizeURLParams {
+    /** OAuth 应用 ID */
+    client_id: string;
+    /** 回调地址，必须与应用配置一致 */
+    redirect_uri: string;
+    /** 权限范围，数组会自动以空格拼接 */
+    scope: OAuthScope | OAuthScope[];
+    /** 可选状态参数，用于防 CSRF 或携带上下文 */
+    state?: string;
+    /** PKCE 的 code_challenge（公共客户端推荐） */
+    code_challenge?: string;
+    /** PKCE 挑战方式，目前固定为 S256 */
+    code_challenge_method?: "S256";
+}
+/**
+ * OAuth scope。
+ * 提供常用 scope 的字面量补全，同时保留 string 扩展以兼容未来新增 scope。
+ */
+type OAuthScope = "read_user_profile" | "read_user_token" | "read_player" | "write_player" | (string & {});
+/**
+ * OAuth access_token 绑定后的 API 客户端。
+ * 使用 Bearer Token 访问用户信息和各游戏 personal 接口。
+ */
+declare class OAuthAuthorizedApi {
+    /** GET /api/v0/user/profile 与 GET /api/v0/user/token */
+    readonly user: OAuthUserApi;
+    /** OAuth 授权后可访问的 maimai personal API */
+    readonly maimai: MaimaiPersonalApi;
+    /** OAuth 授权后可访问的 chunithm personal API */
+    readonly chunithm: ChunithmPersonalApi;
+    constructor(userHttp: KyInstance, maimaiHttp: KyInstance, chunithmHttp: KyInstance);
+}
+
 interface Bests$1 {
     bests: Score$1[];
     selections: Score$1[];
@@ -534,31 +692,6 @@ declare class ChunithmDevApi {
     postHtml(friendCode: number, htmlSource: string): Promise<unknown>;
 }
 
-type PlayerScores$1 = Score$1[];
-
-/**
- * chunithm 个人 API（需用户身份）
- */
-declare class ChunithmPersonalApi {
-    readonly http: KyInstance;
-    constructor(http: KyInstance);
-    /**
-     * 获取玩家信息
-     * GET /api/v0/user/chunithm/player
-     */
-    getPlayer(): Promise<Player$1>;
-    /**
-     * 获取玩家所有成绩
-     * GET /api/v0/user/chunithm/player/scores
-     */
-    getScores(): Promise<PlayerScores$1>;
-    /**
-     * 上传玩家成绩
-     * POST /api/v0/user/chunithm/player/scores
-     */
-    postScores(scores: Score$1[]): Promise<unknown>;
-}
-
 interface SongList$1 {
     songs: Song$2[];
     genres: Genre$1[];
@@ -698,35 +831,6 @@ declare class MaimaiDevApi {
     postHtml(friendCode: number, htmlSource: string): Promise<unknown>;
 }
 
-type PlayerScores = Score[];
-
-/**
- * maimai 个人 API（需用户身份，路径遵循文档）
- */
-declare class MaimaiPersonalApi {
-    readonly http: KyInstance;
-    constructor(http: KyInstance);
-    /**
-     * 获取玩家信息
-     * GET /api/v0/user/maimai/player
-     * @returns PlayerInfo
-     */
-    getPlayer(): Promise<Player>;
-    /**
-     * 获取玩家所有成绩
-     * GET /api/v0/user/maimai/player/scores
-     * @returns PlayerScores
-     */
-    getScores(): Promise<PlayerScores>;
-    /**
-     * 上传玩家成绩
-     * POST /api/v0/user/maimai/player/scores
-     * @param scores 成绩列表
-     * @returns 上传结果
-     */
-    postScores(scores: Score[]): Promise<unknown>;
-}
-
 type DifficultyMap<T> = {
     0: T;
     1: T;
@@ -878,11 +982,75 @@ declare class LxnsApiClient<O extends LxnsApiClientOptions> {
      * chunithm API
      */
     readonly chunithm: ChunithmApiOf<O>;
-    private static readonly BASE_OPTIONS;
     private mountGameApi;
     constructor(config?: Readonly<O>);
 }
 
+interface LxnsOAuthClientOptions {
+    /** OAuth 应用的 client_id */
+    clientId: string;
+    /** OAuth 回调地址，需与应用配置一致 */
+    redirectURI: string;
+    /** 机密客户端使用的 client_secret；PKCE 场景可不传 */
+    clientSecret?: string;
+    /** API 基础地址，默认 https://maimai.lxns.net/api/v0/ */
+    baseURL?: string;
+}
+interface OAuthAuthorizeURLOptions {
+    /** 申请的权限范围 */
+    scope: OAuthAuthorizeURLParams["scope"];
+    /** 可选状态参数，用于防 CSRF 或携带上下文 */
+    state?: string;
+    /** PKCE code_challenge */
+    codeChallenge?: string;
+    /** PKCE 挑战方式，当前仅支持 S256 */
+    codeChallengeMethod?: OAuthAuthorizeURLParams["code_challenge_method"];
+}
+interface OAuthExchangeCodeOptions {
+    /** OAuth 回调返回的 code */
+    code: string;
+    /** PKCE 场景对应的 code_verifier */
+    codeVerifier?: string;
+}
+interface OAuthRefreshTokenOptions {
+    /** 刷新令牌 */
+    refreshToken: string;
+}
+/**
+ * Lxns OAuth 客户端。
+ * 负责授权链接生成、code 换 token、refresh token，以及基于 access_token 创建授权态 API。
+ */
+declare class LxnsOAuthClient {
+    /** 当前 OAuth 客户端配置 */
+    readonly config: LxnsOAuthClientOptions & {
+        baseURL: string;
+    };
+    private readonly http;
+    /**
+     * @param config OAuth 配置
+     */
+    constructor(config: Readonly<LxnsOAuthClientOptions>);
+    /**
+     * 生成 OAuth 授权链接（/oauth/authorize）。
+     * @returns 可直接跳转的授权 URL
+     */
+    createAuthorizeURL({ scope, state, codeChallenge, codeChallengeMethod, }: OAuthAuthorizeURLOptions): string;
+    /**
+     * 使用授权码换取访问令牌（grant_type=authorization_code）。
+     * - 机密客户端：依赖 constructor 传入的 clientSecret
+     * - PKCE 客户端：通过 codeVerifier 交换
+     */
+    exchangeCodeForToken({ code, codeVerifier }: OAuthExchangeCodeOptions): Promise<OAuthTokenResponse>;
+    /**
+     * 使用 refresh_token 刷新访问令牌（grant_type=refresh_token）。
+     */
+    refreshAccessToken({ refreshToken }: OAuthRefreshTokenOptions): Promise<OAuthTokenResponse>;
+    /**
+     * 基于 access_token 创建授权态 API 客户端。
+     */
+    createAuthorizedClient(accessToken: string): OAuthAuthorizedApi;
+}
+
 declare class LxnsApiError extends Error {
     readonly code: number;
     readonly status?: number;
@@ -896,4 +1064,4 @@ declare function isAuthError(error: unknown): error is LxnsApiError;
 declare function isRateLimitError(error: unknown): error is LxnsApiError;
 declare function isServerError(error: unknown): error is LxnsApiError;
 
-export { models$1 as ChunithmModels, LxnsApiClient, LxnsApiError, models as MaimaiModels, isAuthError, isLxnsApiError, isNotFoundError, isRateLimitError, isServerError };
+export { models$1 as ChunithmModels, LxnsApiClient, type LxnsApiClientOptions, LxnsApiError, LxnsOAuthClient, type LxnsOAuthClientOptions, models as MaimaiModels, type OAuthAuthorizeCodeTokenRequest, type OAuthAuthorizeURLOptions, type OAuthAuthorizeURLParams, OAuthAuthorizedApi, type OAuthExchangeCodeOptions, type OAuthRefreshTokenOptions, type OAuthRefreshTokenRequest, type OAuthScope, type OAuthTokenResponse, OAuthUserApi, isAuthError, isLxnsApiError, isNotFoundError, isRateLimitError, isServerError };

package/dist/index.js

@@ -33,10 +33,110 @@ var LevelIndex2 = /* @__PURE__ */ ((LevelIndex3) => {
   return LevelIndex3;
 })(LevelIndex2 || {});
 
+// src/api/chunithm/personal-api.ts
+var ChunithmPersonalApi = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 获取玩家信息
+   * GET /api/v0/user/chunithm/player
+   */
+  async getPlayer() {
+    return this.http.get("player").json();
+  }
+  /**
+   * 获取玩家所有成绩
+   * GET /api/v0/user/chunithm/player/scores
+   */
+  async getScores() {
+    return this.http.get("scores").json();
+  }
+  /**
+   * 上传玩家成绩
+   * POST /api/v0/user/chunithm/player/scores
+   */
+  async postScores(scores) {
+    const body = { scores };
+    return this.http.post("scores", { json: body }).json();
+  }
+};
+
+// src/api/maimai/personal-api.ts
+var MaimaiPersonalApi = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 获取玩家信息
+   * GET /api/v0/user/maimai/player
+   * @returns PlayerInfo
+   */
+  async getPlayer() {
+    return this.http.get("player").json();
+  }
+  /**
+   * 获取玩家所有成绩
+   * GET /api/v0/user/maimai/player/scores
+   * @returns PlayerScores
+   */
+  async getScores() {
+    return this.http.get("scores").json();
+  }
+  /**
+   * 上传玩家成绩
+   * POST /api/v0/user/maimai/player/scores
+   * @param scores 成绩列表
+   * @returns 上传结果
+   */
+  async postScores(scores) {
+    const body = { scores };
+    return this.http.post("scores", { json: body }).json();
+  }
+};
+
+// src/api/oauth/user.ts
+var OAuthUserApi = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 获取用户基本信息
+   * GET /api/v0/user/profile
+   * @returns 用户基本信息
+   */
+  async getProfile() {
+    return this.http.get("profile").json();
+  }
+  /**
+   * 获取用户个人 API 密钥
+   * GET /api/v0/user/token
+   * @returns 用户个人 API 密钥
+   */
+  async getToken() {
+    return this.http.get("token").json();
+  }
+};
+
+// src/api/oauth/oauth.ts
+var OAuthAuthorizedApi = class {
+  /** GET /api/v0/user/profile 与 GET /api/v0/user/token */
+  user;
+  /** OAuth 授权后可访问的 maimai personal API */
+  maimai;
+  /** OAuth 授权后可访问的 chunithm personal API */
+  chunithm;
+  constructor(userHttp, maimaiHttp, chunithmHttp) {
+    this.user = new OAuthUserApi(userHttp);
+    this.maimai = new MaimaiPersonalApi(maimaiHttp);
+    this.chunithm = new ChunithmPersonalApi(chunithmHttp);
+  }
+};
+
 // src/client/lxns-api-client.ts
 import ky from "ky";
 
-// src/api/chunithm/dev.ts
+// src/api/chunithm/dev-api.ts
 var ChunithmDevApi = class {
   constructor(http) {
     this.http = http;
@@ -136,36 +236,7 @@ var ChunithmDevApi = class {
   }
 };
 
-// src/api/chunithm/personal.ts
-var ChunithmPersonalApi = class {
-  constructor(http) {
-    this.http = http;
-  }
-  /**
-   * 获取玩家信息
-   * GET /api/v0/user/chunithm/player
-   */
-  async getPlayer() {
-    return this.http.get("player").json();
-  }
-  /**
-   * 获取玩家所有成绩
-   * GET /api/v0/user/chunithm/player/scores
-   */
-  async getScores() {
-    return this.http.get("scores").json();
-  }
-  /**
-   * 上传玩家成绩
-   * POST /api/v0/user/chunithm/player/scores
-   */
-  async postScores(scores) {
-    const body = { scores };
-    return this.http.post("scores", { json: body }).json();
-  }
-};
-
-// src/api/chunithm/public.ts
+// src/api/chunithm/public-api.ts
 var ChunithmPublicApi = class {
   constructor(http) {
     this.http = http;
@@ -208,7 +279,7 @@ var ChunithmPublicApi = class {
   }
 };
 
-// src/api/maimai/dev.ts
+// src/api/maimai/dev-api.ts
 var MaimaiDevApi = class {
   constructor(http) {
     this.http = http;
@@ -327,39 +398,6 @@ var MaimaiDevApi = class {
   }
 };
 
-// src/api/maimai/personal.ts
-var MaimaiPersonalApi = class {
-  constructor(http) {
-    this.http = http;
-  }
-  /**
-   * 获取玩家信息
-   * GET /api/v0/user/maimai/player
-   * @returns PlayerInfo
-   */
-  async getPlayer() {
-    return this.http.get("player").json();
-  }
-  /**
-   * 获取玩家所有成绩
-   * GET /api/v0/user/maimai/player/scores
-   * @returns PlayerScores
-   */
-  async getScores() {
-    return this.http.get("scores").json();
-  }
-  /**
-   * 上传玩家成绩
-   * POST /api/v0/user/maimai/player/scores
-   * @param scores 成绩列表
-   * @returns 上传结果
-   */
-  async postScores(scores) {
-    const body = { scores };
-    return this.http.post("scores", { json: body }).json();
-  }
-};
-
 // src/api/maimai/entities/song.ts
 var LevelArray = [
   "basic",
@@ -420,7 +458,7 @@ var Song = class {
   }
 };
 
-// src/api/maimai/public.ts
+// src/api/maimai/public-api.ts
 var MaimaiPublicApi = class {
   constructor(http) {
     this.http = http;
@@ -528,7 +566,7 @@ function isServerError(error) {
   return typeof code === "number" && code >= 500;
 }
 
-// src/client/lxns-api-client.ts
+// src/client/http-options.ts
 function parseLxnsJson(text) {
   const payload = JSON.parse(text);
   if (payload.success === false) {
@@ -565,7 +603,16 @@ async function wrapKyError(error) {
     status
   );
 }
-var LxnsApiClient = class _LxnsApiClient {
+var LXNS_HTTP_OPTIONS = {
+  parseJson: parseLxnsJson,
+  throwHttpErrors: true,
+  hooks: {
+    beforeError: [wrapKyError]
+  }
+};
+
+// src/client/lxns-api-client.ts
+var LxnsApiClient = class {
   config;
   /**
    * maimai API
@@ -575,13 +622,6 @@ var LxnsApiClient = class _LxnsApiClient {
    * chunithm API
    */
   chunithm;
-  static BASE_OPTIONS = {
-    parseJson: parseLxnsJson,
-    throwHttpErrors: true,
-    hooks: {
-      beforeError: [wrapKyError]
-    }
-  };
   mountGameApi({
     public: publicApi,
     dev,
@@ -608,21 +648,21 @@ var LxnsApiClient = class _LxnsApiClient {
     const { baseURL, devAccessToken, personalAccessToken } = this.config;
     const maimaiHttpPublic = ky.create({
       prefixUrl: new URL("maimai/", baseURL),
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     });
     const maimaiHttpDev = devAccessToken ? ky.create({
       prefixUrl: new URL("maimai/", baseURL),
       headers: {
         Authorization: devAccessToken
       },
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     }) : void 0;
     const maimaiHttpPersonal = personalAccessToken ? ky.create({
       prefixUrl: new URL("user/maimai/", baseURL),
       headers: {
         "X-User-Token": personalAccessToken
       },
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     }) : void 0;
     this.maimai = this.mountGameApi({
       public: new MaimaiPublicApi(maimaiHttpPublic),
@@ -640,21 +680,21 @@ var LxnsApiClient = class _LxnsApiClient {
     });
     const chunithmHttpPublic = ky.create({
       prefixUrl: new URL("chunithm/", baseURL),
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     });
     const chunithmHttpDev = devAccessToken ? ky.create({
       prefixUrl: new URL("chunithm/", baseURL),
       headers: {
         Authorization: devAccessToken
       },
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     }) : void 0;
     const chunithmHttpPersonal = personalAccessToken ? ky.create({
       prefixUrl: new URL("user/chunithm/", baseURL),
       headers: {
         "X-User-Token": personalAccessToken
       },
-      ..._LxnsApiClient.BASE_OPTIONS
+      ...LXNS_HTTP_OPTIONS
     }) : void 0;
     this.chunithm = this.mountGameApi({
       public: new ChunithmPublicApi(chunithmHttpPublic),
@@ -670,11 +710,141 @@ var LxnsApiClient = class _LxnsApiClient {
     });
   }
 };
+
+// src/client/lxns-oauth-client.ts
+import ky2 from "ky";
+var LxnsOAuthClient = class {
+  /** 当前 OAuth 客户端配置 */
+  config;
+  http;
+  /**
+   * @param config OAuth 配置
+   */
+  constructor(config) {
+    this.config = {
+      ...config,
+      baseURL: config.baseURL ?? "https://maimai.lxns.net/api/v0/"
+    };
+    this.http = ky2.create({
+      prefixUrl: new URL("oauth/", this.config.baseURL),
+      ...LXNS_HTTP_OPTIONS
+    });
+  }
+  /**
+   * 生成 OAuth 授权链接（/oauth/authorize）。
+   * @returns 可直接跳转的授权 URL
+   */
+  createAuthorizeURL({
+    scope,
+    state,
+    codeChallenge,
+    codeChallengeMethod
+  }) {
+    const url = new URL("/oauth/authorize", this.config.baseURL);
+    const search = new URLSearchParams({
+      response_type: "code",
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectURI,
+      scope: Array.isArray(scope) ? scope.join(" ") : scope
+    });
+    if (state) {
+      search.set("state", state);
+    }
+    if (codeChallenge) {
+      search.set("code_challenge", codeChallenge);
+    }
+    if (codeChallengeMethod) {
+      search.set("code_challenge_method", codeChallengeMethod);
+    }
+    url.search = search.toString();
+    return url.toString();
+  }
+  /**
+   * 使用授权码换取访问令牌（grant_type=authorization_code）。
+   * - 机密客户端：依赖 constructor 传入的 clientSecret
+   * - PKCE 客户端：通过 codeVerifier 交换
+   */
+  async exchangeCodeForToken({ code, codeVerifier }) {
+    const payload = codeVerifier ? {
+      client_id: this.config.clientId,
+      code,
+      redirect_uri: this.config.redirectURI,
+      code_verifier: codeVerifier
+    } : {
+      client_id: this.config.clientId,
+      code,
+      redirect_uri: this.config.redirectURI,
+      client_secret: this.config.clientSecret ?? ""
+    };
+    if (!codeVerifier && !this.config.clientSecret) {
+      throw new Error(
+        "clientSecret is required when codeVerifier is not provided."
+      );
+    }
+    return this.http.post("token", {
+      json: {
+        ...payload,
+        grant_type: "authorization_code"
+      }
+    }).json();
+  }
+  /**
+   * 使用 refresh_token 刷新访问令牌（grant_type=refresh_token）。
+   */
+  async refreshAccessToken({ refreshToken }) {
+    const payload = {
+      client_id: this.config.clientId,
+      refresh_token: refreshToken,
+      client_secret: this.config.clientSecret
+    };
+    return this.http.post("token", {
+      json: {
+        ...payload,
+        grant_type: "refresh_token"
+      }
+    }).json();
+  }
+  /**
+   * 基于 access_token 创建授权态 API 客户端。
+   */
+  createAuthorizedClient(accessToken) {
+    const authorization = `Bearer ${accessToken}`;
+    const userHttp = ky2.create({
+      prefixUrl: new URL("user/", this.config.baseURL),
+      headers: {
+        Authorization: authorization
+      },
+      ...LXNS_HTTP_OPTIONS
+    });
+    const maimaiPersonalHttp = ky2.create({
+      prefixUrl: new URL("user/maimai/", this.config.baseURL),
+      headers: {
+        Authorization: authorization
+      },
+      ...LXNS_HTTP_OPTIONS
+    });
+    const chunithmPersonalHttp = ky2.create({
+      prefixUrl: new URL("user/chunithm/", this.config.baseURL),
+      headers: {
+        Authorization: authorization
+      },
+      ...LXNS_HTTP_OPTIONS
+    });
+    return new OAuthAuthorizedApi(
+      userHttp,
+      maimaiPersonalHttp,
+      chunithmPersonalHttp
+    );
+  }
+};
 export {
   models_exports as ChunithmModels,
   LxnsApiClient,
   LxnsApiError,
+  LxnsOAuthClient,
   models_exports2 as MaimaiModels,
+  OAuthAuthorizedApi,
+  OAuthUserApi,
   isAuthError,
   isLxnsApiError,
   isNotFoundError,

package/package.json

@@ -12,7 +12,7 @@
     "api-client"
   ],
   "author": "amatsuka <amatsukamao@qq.com>",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "license": "MIT",
   "repository": {
     "type": "git",