@yuuko1410/feishu-bitable 0.0.4 → 0.0.5

package/README.md

@@ -17,6 +17,7 @@
 - 支持小文件直接上传
 - 支持大文件自动切换分片上传
 - 支持文件下载
+- 支持 H5 OAuth 登录（生成登录链接、code 换 token、获取用户信息）
 - 支持字段值归一化
 - 支持批量请求自动分片
 - 支持并发控制
@@ -33,11 +34,13 @@ packages/feishu-bitable/
 ├── tsconfig.build.json
 ├── src/
 │   ├── client.ts
+│   ├── auth.ts
 │   ├── errors.ts
 │   ├── index.ts
 │   ├── types.ts
 │   └── utils.ts
 ├── test/
+│   ├── auth.test.ts
 │   └── bitable.test.ts
 └── lib/                     # bun run build 后生成
 ```
@@ -81,6 +84,7 @@ npm install @yuuko1410/feishu-bitable
 主导出：
 
 - `Bitable`
+- `FeishuOAuthClient`
 - `FeishuBitableError`
 - `AppType`
 - `Domain`
@@ -89,6 +93,11 @@ npm install @yuuko1410/feishu-bitable
 类型导出：
 
 - `BitableConstructorOptions`
+- `FeishuOAuthConstructorOptions`
+- `BuildOAuthLoginUrlOptions`
+- `OAuthTokenInfo`
+- `OAuthUserInfo`
+- `OAuthCallbackResult`
 - `FetchAllRecordsOptions`
 - `BatchOperationOptions`
 - `UpdateRecordsOptions`
@@ -141,6 +150,7 @@ const bitable = Bitable.fromEnv();
 - `FEISHU_APP_ID`
 - `FEISHU_APP_SECRET`
 - `FEISHU_APP_TOKEN`
+- `FEISHU_OAUTH_REDIRECT_URI`（OAuth 登录回调地址）
 
 ## 构造参数说明
 
@@ -156,6 +166,15 @@ const bitable = Bitable.fromEnv();
 - `defaultConcurrency`：默认并发数，默认 `1`
 - `sdkClient`：可注入已创建的官方 SDK client，便于测试或复用
 
+`FeishuOAuthConstructorOptions` 支持：
+
+- `appId`：飞书应用 `app_id`
+- `appSecret`：飞书应用 `app_secret`
+- `redirectUri`：OAuth 回调地址
+- `domain`：飞书 SDK `Domain`
+- `sdkClient`：可注入官方 SDK client
+- `logger`：可注入日志器；传 `null` 可禁用日志
+
 ## 公开 API
 
 ### 1. `fetchAllRecords`
@@ -352,6 +371,84 @@ const buffer = await bitable.downloadFile("file_token");
 const buffer = await bitable.downLoadFile("file_token");
 ```
 
+### 9. `FeishuOAuthClient.buildLoginUrl`
+
+生成 H5 飞书登录链接。
+
+```ts
+import { FeishuOAuthClient } from "@yuuko1410/feishu-bitable";
+
+const oauth = FeishuOAuthClient.fromEnv();
+const loginUrl = oauth.buildLoginUrl({
+  state: "csrf_state_123",
+  scope: ["contact:user.base:readonly"],
+});
+```
+
+### 10. `FeishuOAuthClient.exchangeCodeForUserToken`
+
+后端使用回调 `code` 换取 `user_access_token`。
+
+```ts
+const token = await oauth.exchangeCodeForUserToken(code);
+```
+
+### 11. `FeishuOAuthClient.getUserInfo`
+
+使用 `user_access_token` 拉取飞书用户信息。
+
+```ts
+const user = await oauth.getUserInfo(token.access_token);
+```
+
+### 12. `FeishuOAuthClient.handleCallback`
+
+最简回调处理：一键完成 `code -> token -> user`。
+
+```ts
+const result = await oauth.handleCallback(code);
+// result.token
+// result.user
+```
+
+## H5 登录最简接入
+
+前端按钮跳转：
+
+```ts
+window.location.href = "/api/auth/feishu/login";
+```
+
+后端示例（Express/SvelteKit 思路一致）：
+
+```ts
+import { FeishuOAuthClient } from "@yuuko1410/feishu-bitable";
+
+const oauth = FeishuOAuthClient.fromEnv();
+
+export async function loginHandler() {
+  const state = crypto.randomUUID();
+  const loginUrl = oauth.buildLoginUrl({
+    state,
+    scope: ["contact:user.base:readonly"],
+  });
+
+  return Response.redirect(loginUrl, 302);
+}
+
+export async function callbackHandler(code: string) {
+  const { token, user } = await oauth.handleCallback(code);
+
+  // 这里创建你自己的业务登录态（session/JWT）
+  // 不建议把 user_access_token 暴露给前端
+  return {
+    uid: user.open_id ?? user.user_id,
+    name: user.name,
+    tokenType: token.token_type,
+  };
+}
+```
+
 ## 自动行为说明
 
 ### 自动分页
@@ -449,6 +546,9 @@ await bitable.deleteList("table_id", ["recyyy"]);
 - 数组式批量更新到官方 payload 的转换
 - 官方批量更新 payload 透传
 - 文件下载
+- OAuth 登录链接生成
+- OAuth code 换 token
+- OAuth 回调获取用户信息
 - 凭证缺失报错
 
 ## 发布

package/lib/auth.d.ts

@@ -0,0 +1,20 @@
+import * as lark from "@larksuiteoapi/node-sdk";
+import type { BitableLogger, BuildOAuthLoginUrlOptions, FeishuOAuthConstructorOptions, OAuthCallbackResult, OAuthTokenInfo, OAuthUserInfo } from "./types";
+type OAuthSdkClient = Pick<lark.Client, "authen">;
+export declare class FeishuOAuthClient {
+    readonly appId: string;
+    readonly appSecret: string;
+    readonly redirectUri?: string;
+    readonly domain: lark.Domain | string;
+    readonly logger: BitableLogger | null;
+    readonly client: OAuthSdkClient;
+    constructor(options?: FeishuOAuthConstructorOptions);
+    static fromEnv(env?: NodeJS.ProcessEnv): FeishuOAuthClient;
+    buildLoginUrl(options: BuildOAuthLoginUrlOptions): string;
+    exchangeCodeForUserToken(code: string): Promise<OAuthTokenInfo>;
+    refreshUserAccessToken(refreshToken: string): Promise<OAuthTokenInfo>;
+    getUserInfo(userAccessToken: string): Promise<OAuthUserInfo>;
+    handleCallback(code: string): Promise<OAuthCallbackResult>;
+    private logInfo;
+}
+export {};

package/lib/index.cjs

@@ -65,6 +65,7 @@ var exports_src = {};
 __export(exports_src, {
   default: () => src_default,
   LoggerLevel: () => import_node_sdk.LoggerLevel,
+  FeishuOAuthClient: () => FeishuOAuthClient,
   FeishuBitableError: () => FeishuBitableError,
   Domain: () => import_node_sdk.Domain,
   Bitable: () => Bitable,
@@ -675,6 +676,183 @@ class Bitable {
   }
 }
 
+// src/auth.ts
+var lark2 = __toESM(require("@larksuiteoapi/node-sdk"));
+var DEFAULT_LOGGER2 = {
+  info(message, meta) {
+    if (meta) {
+      console.info(`[feishu-bitable] ${message}`, meta);
+      return;
+    }
+    console.info(`[feishu-bitable] ${message}`);
+  },
+  warn(message, meta) {
+    if (meta) {
+      console.warn(`[feishu-bitable] ${message}`, meta);
+      return;
+    }
+    console.warn(`[feishu-bitable] ${message}`);
+  },
+  error(message, meta) {
+    if (meta) {
+      console.error(`[feishu-bitable] ${message}`, meta);
+      return;
+    }
+    console.error(`[feishu-bitable] ${message}`);
+  }
+};
+
+class FeishuOAuthClient {
+  appId;
+  appSecret;
+  redirectUri;
+  domain;
+  logger;
+  client;
+  constructor(options = {}) {
+    const appId = options.appId ?? process.env.FEISHU_APP_ID;
+    const appSecret = options.appSecret ?? process.env.FEISHU_APP_SECRET;
+    if (!appId || !appSecret) {
+      throw new FeishuBitableError("appId and appSecret are required. Pass them in constructor or provide FEISHU_APP_ID and FEISHU_APP_SECRET.");
+    }
+    this.appId = appId;
+    this.appSecret = appSecret;
+    this.redirectUri = options.redirectUri;
+    this.domain = options.domain ?? lark2.Domain.Feishu;
+    this.logger = options.logger === null ? null : options.logger ?? DEFAULT_LOGGER2;
+    this.client = options.sdkClient ?? new lark2.Client({
+      appId: this.appId,
+      appSecret: this.appSecret,
+      appType: lark2.AppType.SelfBuild,
+      domain: this.domain
+    });
+  }
+  static fromEnv(env = process.env) {
+    return new FeishuOAuthClient({
+      appId: env.FEISHU_APP_ID,
+      appSecret: env.FEISHU_APP_SECRET,
+      redirectUri: env.FEISHU_OAUTH_REDIRECT_URI
+    });
+  }
+  buildLoginUrl(options) {
+    const redirectUri = options.redirectUri ?? this.redirectUri;
+    if (!redirectUri) {
+      throw new FeishuBitableError("redirectUri is required. Pass it into constructor or buildLoginUrl options.");
+    }
+    const scope = Array.isArray(options.scope) ? options.scope.join(" ") : options.scope;
+    const url = new URL("/open-apis/authen/v1/authorize", resolveOpenDomain(this.domain));
+    url.searchParams.set("app_id", this.appId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("state", options.state);
+    if (scope?.trim()) {
+      url.searchParams.set("scope", scope.trim());
+    }
+    this.logInfo("oauth buildLoginUrl", {
+      redirectUri,
+      hasScope: Boolean(scope),
+      state: options.state
+    });
+    return url.toString();
+  }
+  async exchangeCodeForUserToken(code) {
+    if (!code.trim()) {
+      throw new FeishuBitableError("code is required to exchange user token.");
+    }
+    this.logInfo("oauth exchangeCodeForUserToken started");
+    const response = assertFeishuResponse(await this.client.authen.v1.oidcAccessToken.create({
+      data: {
+        grant_type: "authorization_code",
+        code
+      }
+    }), "oauth exchange code");
+    const data = response.data;
+    if (!data?.access_token || !data.token_type) {
+      throw new FeishuBitableError("oauth exchange code failed: missing token fields.", {
+        details: response
+      });
+    }
+    const token = {
+      access_token: data.access_token,
+      refresh_token: data.refresh_token,
+      token_type: data.token_type,
+      expires_in: data.expires_in,
+      refresh_expires_in: data.refresh_expires_in,
+      scope: data.scope
+    };
+    this.logInfo("oauth exchangeCodeForUserToken succeeded", {
+      hasRefreshToken: Boolean(token.refresh_token),
+      expiresIn: token.expires_in
+    });
+    return token;
+  }
+  async refreshUserAccessToken(refreshToken) {
+    if (!refreshToken.trim()) {
+      throw new FeishuBitableError("refreshToken is required to refresh user token.");
+    }
+    this.logInfo("oauth refreshUserAccessToken started");
+    const response = assertFeishuResponse(await this.client.authen.v1.oidcRefreshAccessToken.create({
+      data: {
+        grant_type: "refresh_token",
+        refresh_token: refreshToken
+      }
+    }), "oauth refresh token");
+    const data = response.data;
+    if (!data?.access_token || !data.token_type) {
+      throw new FeishuBitableError("oauth refresh token failed: missing token fields.", {
+        details: response
+      });
+    }
+    const token = {
+      access_token: data.access_token,
+      refresh_token: data.refresh_token,
+      token_type: data.token_type,
+      expires_in: data.expires_in,
+      refresh_expires_in: data.refresh_expires_in,
+      scope: data.scope
+    };
+    this.logInfo("oauth refreshUserAccessToken succeeded", {
+      hasRefreshToken: Boolean(token.refresh_token),
+      expiresIn: token.expires_in
+    });
+    return token;
+  }
+  async getUserInfo(userAccessToken) {
+    if (!userAccessToken.trim()) {
+      throw new FeishuBitableError("userAccessToken is required to get user info.");
+    }
+    this.logInfo("oauth getUserInfo started");
+    const response = assertFeishuResponse(await this.client.authen.v1.userInfo.get({}, lark2.withUserAccessToken(userAccessToken)), "oauth get user info");
+    this.logInfo("oauth getUserInfo succeeded", {
+      openId: response.data?.open_id,
+      userId: response.data?.user_id
+    });
+    return response.data ?? {};
+  }
+  async handleCallback(code) {
+    const token = await this.exchangeCodeForUserToken(code);
+    const user = await this.getUserInfo(token.access_token);
+    return { token, user };
+  }
+  logInfo(message, meta) {
+    this.logger?.info(message, meta);
+  }
+}
+function resolveOpenDomain(domain) {
+  if (domain === lark2.Domain.Lark) {
+    return "https://open.larksuite.com";
+  }
+  if (domain === lark2.Domain.Feishu) {
+    return "https://open.feishu.cn";
+  }
+  if (typeof domain === "string") {
+    if (domain.includes("larksuite")) {
+      return "https://open.larksuite.com";
+    }
+    return "https://open.feishu.cn";
+  }
+  return "https://open.feishu.cn";
+}
+
 // src/index.ts
 var import_node_sdk = require("@larksuiteoapi/node-sdk");
 var src_default = Bitable;

package/lib/index.d.ts

@@ -1,6 +1,8 @@
 import { Bitable } from "./client";
+import { FeishuOAuthClient } from "./auth";
 export { Bitable };
+export { FeishuOAuthClient };
 export { FeishuBitableError } from "./errors";
 export { AppType, Domain, LoggerLevel } from "@larksuiteoapi/node-sdk";
-export type { BatchOperationOptions, BitableBatchUpdatePayload, BitableBatchUpdateResponse, BitableConstructorOptions, BitableFieldValue, BitableFilterCondition, BitableFilterGroup, BitableInsertRecord, BitableLocationValue, BitableLogger, BitableMemberValue, BitableRecord, BitableRecordFields, BitableSort, BitableTextValue, BitableUpdateRecord, FetchAllRecordsOptions, MediaParentType, UpdateRecordsOptions, UploadFileOptions, UploadableFile, } from "./types";
+export type { BatchOperationOptions, BitableBatchUpdatePayload, BitableBatchUpdateResponse, BitableConstructorOptions, BitableFieldValue, BitableFilterCondition, BitableFilterGroup, BitableInsertRecord, BitableLocationValue, BitableLogger, BitableMemberValue, BitableRecord, BitableRecordFields, BitableSort, BitableTextValue, BitableUpdateRecord, BuildOAuthLoginUrlOptions, FetchAllRecordsOptions, FeishuOAuthConstructorOptions, MediaParentType, OAuthCallbackResult, OAuthTokenInfo, OAuthUserInfo, UpdateRecordsOptions, UploadFileOptions, UploadableFile, } from "./types";
 export default Bitable;

package/lib/index.js

@@ -601,14 +601,192 @@ class Bitable {
   }
 }
 
+// src/auth.ts
+import * as lark2 from "@larksuiteoapi/node-sdk";
+var DEFAULT_LOGGER2 = {
+  info(message, meta) {
+    if (meta) {
+      console.info(`[feishu-bitable] ${message}`, meta);
+      return;
+    }
+    console.info(`[feishu-bitable] ${message}`);
+  },
+  warn(message, meta) {
+    if (meta) {
+      console.warn(`[feishu-bitable] ${message}`, meta);
+      return;
+    }
+    console.warn(`[feishu-bitable] ${message}`);
+  },
+  error(message, meta) {
+    if (meta) {
+      console.error(`[feishu-bitable] ${message}`, meta);
+      return;
+    }
+    console.error(`[feishu-bitable] ${message}`);
+  }
+};
+
+class FeishuOAuthClient {
+  appId;
+  appSecret;
+  redirectUri;
+  domain;
+  logger;
+  client;
+  constructor(options = {}) {
+    const appId = options.appId ?? process.env.FEISHU_APP_ID;
+    const appSecret = options.appSecret ?? process.env.FEISHU_APP_SECRET;
+    if (!appId || !appSecret) {
+      throw new FeishuBitableError("appId and appSecret are required. Pass them in constructor or provide FEISHU_APP_ID and FEISHU_APP_SECRET.");
+    }
+    this.appId = appId;
+    this.appSecret = appSecret;
+    this.redirectUri = options.redirectUri;
+    this.domain = options.domain ?? lark2.Domain.Feishu;
+    this.logger = options.logger === null ? null : options.logger ?? DEFAULT_LOGGER2;
+    this.client = options.sdkClient ?? new lark2.Client({
+      appId: this.appId,
+      appSecret: this.appSecret,
+      appType: lark2.AppType.SelfBuild,
+      domain: this.domain
+    });
+  }
+  static fromEnv(env = process.env) {
+    return new FeishuOAuthClient({
+      appId: env.FEISHU_APP_ID,
+      appSecret: env.FEISHU_APP_SECRET,
+      redirectUri: env.FEISHU_OAUTH_REDIRECT_URI
+    });
+  }
+  buildLoginUrl(options) {
+    const redirectUri = options.redirectUri ?? this.redirectUri;
+    if (!redirectUri) {
+      throw new FeishuBitableError("redirectUri is required. Pass it into constructor or buildLoginUrl options.");
+    }
+    const scope = Array.isArray(options.scope) ? options.scope.join(" ") : options.scope;
+    const url = new URL("/open-apis/authen/v1/authorize", resolveOpenDomain(this.domain));
+    url.searchParams.set("app_id", this.appId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("state", options.state);
+    if (scope?.trim()) {
+      url.searchParams.set("scope", scope.trim());
+    }
+    this.logInfo("oauth buildLoginUrl", {
+      redirectUri,
+      hasScope: Boolean(scope),
+      state: options.state
+    });
+    return url.toString();
+  }
+  async exchangeCodeForUserToken(code) {
+    if (!code.trim()) {
+      throw new FeishuBitableError("code is required to exchange user token.");
+    }
+    this.logInfo("oauth exchangeCodeForUserToken started");
+    const response = assertFeishuResponse(await this.client.authen.v1.oidcAccessToken.create({
+      data: {
+        grant_type: "authorization_code",
+        code
+      }
+    }), "oauth exchange code");
+    const data = response.data;
+    if (!data?.access_token || !data.token_type) {
+      throw new FeishuBitableError("oauth exchange code failed: missing token fields.", {
+        details: response
+      });
+    }
+    const token = {
+      access_token: data.access_token,
+      refresh_token: data.refresh_token,
+      token_type: data.token_type,
+      expires_in: data.expires_in,
+      refresh_expires_in: data.refresh_expires_in,
+      scope: data.scope
+    };
+    this.logInfo("oauth exchangeCodeForUserToken succeeded", {
+      hasRefreshToken: Boolean(token.refresh_token),
+      expiresIn: token.expires_in
+    });
+    return token;
+  }
+  async refreshUserAccessToken(refreshToken) {
+    if (!refreshToken.trim()) {
+      throw new FeishuBitableError("refreshToken is required to refresh user token.");
+    }
+    this.logInfo("oauth refreshUserAccessToken started");
+    const response = assertFeishuResponse(await this.client.authen.v1.oidcRefreshAccessToken.create({
+      data: {
+        grant_type: "refresh_token",
+        refresh_token: refreshToken
+      }
+    }), "oauth refresh token");
+    const data = response.data;
+    if (!data?.access_token || !data.token_type) {
+      throw new FeishuBitableError("oauth refresh token failed: missing token fields.", {
+        details: response
+      });
+    }
+    const token = {
+      access_token: data.access_token,
+      refresh_token: data.refresh_token,
+      token_type: data.token_type,
+      expires_in: data.expires_in,
+      refresh_expires_in: data.refresh_expires_in,
+      scope: data.scope
+    };
+    this.logInfo("oauth refreshUserAccessToken succeeded", {
+      hasRefreshToken: Boolean(token.refresh_token),
+      expiresIn: token.expires_in
+    });
+    return token;
+  }
+  async getUserInfo(userAccessToken) {
+    if (!userAccessToken.trim()) {
+      throw new FeishuBitableError("userAccessToken is required to get user info.");
+    }
+    this.logInfo("oauth getUserInfo started");
+    const response = assertFeishuResponse(await this.client.authen.v1.userInfo.get({}, lark2.withUserAccessToken(userAccessToken)), "oauth get user info");
+    this.logInfo("oauth getUserInfo succeeded", {
+      openId: response.data?.open_id,
+      userId: response.data?.user_id
+    });
+    return response.data ?? {};
+  }
+  async handleCallback(code) {
+    const token = await this.exchangeCodeForUserToken(code);
+    const user = await this.getUserInfo(token.access_token);
+    return { token, user };
+  }
+  logInfo(message, meta) {
+    this.logger?.info(message, meta);
+  }
+}
+function resolveOpenDomain(domain) {
+  if (domain === lark2.Domain.Lark) {
+    return "https://open.larksuite.com";
+  }
+  if (domain === lark2.Domain.Feishu) {
+    return "https://open.feishu.cn";
+  }
+  if (typeof domain === "string") {
+    if (domain.includes("larksuite")) {
+      return "https://open.larksuite.com";
+    }
+    return "https://open.feishu.cn";
+  }
+  return "https://open.feishu.cn";
+}
+
 // src/index.ts
-import { AppType as AppType2, Domain as Domain2, LoggerLevel } from "@larksuiteoapi/node-sdk";
+import { AppType as AppType3, Domain as Domain3, LoggerLevel } from "@larksuiteoapi/node-sdk";
 var src_default = Bitable;
 export {
   src_default as default,
   LoggerLevel,
+  FeishuOAuthClient,
   FeishuBitableError,
-  Domain2 as Domain,
+  Domain3 as Domain,
   Bitable,
-  AppType2 as AppType
+  AppType3 as AppType
 };

package/lib/types.d.ts

@@ -83,6 +83,47 @@ export interface BitableConstructorOptions {
     sdkClient?: lark.Client;
     logger?: BitableLogger | null;
 }
+export interface FeishuOAuthConstructorOptions {
+    appId?: string;
+    appSecret?: string;
+    redirectUri?: string;
+    domain?: lark.Domain | string;
+    sdkClient?: lark.Client;
+    logger?: BitableLogger | null;
+}
+export interface BuildOAuthLoginUrlOptions {
+    state: string;
+    redirectUri?: string;
+    scope?: string | string[];
+}
+export interface OAuthTokenInfo {
+    access_token: string;
+    refresh_token?: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_expires_in?: number;
+    scope?: string;
+}
+export interface OAuthUserInfo {
+    name?: string;
+    en_name?: string;
+    avatar_url?: string;
+    avatar_thumb?: string;
+    avatar_middle?: string;
+    avatar_big?: string;
+    open_id?: string;
+    union_id?: string;
+    email?: string;
+    enterprise_email?: string;
+    user_id?: string;
+    mobile?: string;
+    tenant_key?: string;
+    employee_no?: string;
+}
+export interface OAuthCallbackResult {
+    token: OAuthTokenInfo;
+    user: OAuthUserInfo;
+}
 export interface FetchAllRecordsOptions {
     viewId?: string;
     fieldNames?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuuko1410/feishu-bitable",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "基于 Bun + TypeScript + 飞书官方 SDK 的多维表格操作库",
   "type": "module",
   "main": "./lib/index.cjs",