@yuuko1410/feishu-bitable 0.0.3 → 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/client.d.ts

@@ -37,4 +37,5 @@ export declare class Bitable {
     private logWarn;
     private logError;
     private getErrorMeta;
+    private logRequest;
 }

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,
@@ -285,7 +286,7 @@ class Bitable {
     }, async () => {
       const token = this.resolveAppToken(appToken);
       const pageSize = Math.max(1, Math.min(options.pageSize ?? FEISHU_BATCH_LIMIT, FEISHU_BATCH_LIMIT));
-      const iterator = await this.client.bitable.v1.appTableRecord.searchWithIterator({
+      const request = {
         path: {
           app_token: token,
           table_id: tableId
@@ -301,7 +302,8 @@ class Bitable {
           sort: options.sort,
           automatic_fields: options.automaticFields
         }
-      });
+      };
+      const iterator = await this.client.bitable.v1.appTableRecord.searchWithIterator(this.logRequest("fetchAllRecords request", request));
       const allRecords = [];
       for await (const page of iterator) {
         const items = page?.items ?? [];
@@ -326,12 +328,15 @@ class Bitable {
       }
       const token = this.resolveAppToken(options.appToken);
       const chunks = chunkArray(records, options.chunkSize ?? FEISHU_BATCH_LIMIT);
-      const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => this.withRetry("insert records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchCreate({
-        path: { app_token: token, table_id: tableId },
-        data: {
-          records: chunk.map((fields) => ({ fields }))
-        }
-      }), "insert records")));
+      const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => this.withRetry("insert records", async () => {
+        const request = {
+          path: { app_token: token, table_id: tableId },
+          data: {
+            records: chunk.map((fields) => ({ fields }))
+          }
+        };
+        return assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchCreate(this.logRequest("insertList request", request)), "insert records");
+      }));
       this.logInfo("insertList completed", {
         tableId,
         chunkCount: chunks.length
@@ -358,8 +363,18 @@ class Bitable {
       const token = this.resolveAppToken(options.appToken);
       const chunks = chunkArray(records, options.chunkSize ?? FEISHU_BATCH_LIMIT);
       const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk, index) => {
-        const batchRecords = chunk.map((record) => {
+        const batchRecords = chunk.map((record, recordIndex) => {
           const { recordId, fields } = splitUpdateRecord(record);
+          if (!recordId || !recordId.trim()) {
+            throw new FeishuBitableError(`updateRecords failed: record_id is required for chunk ${index}, item ${recordIndex}`, {
+              details: {
+                tableId,
+                chunkIndex: index,
+                recordIndex,
+                record
+              }
+            });
+          }
           if (Object.keys(fields).length === 0) {
             return null;
           }
@@ -418,12 +433,15 @@ class Bitable {
       }
       const token = this.resolveAppToken(options.appToken);
       const chunks = chunkArray(recordIds, options.chunkSize ?? FEISHU_BATCH_LIMIT);
-      const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => this.withRetry("delete records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchDelete({
-        path: { app_token: token, table_id: tableId },
-        data: {
-          records: chunk
-        }
-      }), "delete records")));
+      const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => this.withRetry("delete records", async () => {
+        const request = {
+          path: { app_token: token, table_id: tableId },
+          data: {
+            records: chunk
+          }
+        };
+        return assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchDelete(this.logRequest("deleteList request", request)), "delete records");
+      }));
       this.logInfo("deleteList completed", {
         tableId,
         chunkCount: chunks.length
@@ -445,25 +463,37 @@ class Bitable {
         mode: buffer.byteLength <= FEISHU_SIMPLE_UPLOAD_LIMIT ? "simple" : "multipart"
       });
       if (buffer.byteLength <= FEISHU_SIMPLE_UPLOAD_LIMIT) {
-        return await this.withRetry("upload file", async () => this.client.drive.v1.media.uploadAll({
+        return await this.withRetry("upload file", async () => {
+          const request = {
+            data: {
+              file_name: fileName,
+              parent_type: options.parentType,
+              parent_node: options.parentNode,
+              size: buffer.byteLength,
+              extra: options.extra,
+              file: buffer
+            }
+          };
+          this.logRequest("uploadFile request", {
+            data: {
+              ...request.data,
+              file: `[Buffer ${buffer.byteLength} bytes]`
+            }
+          });
+          return this.client.drive.v1.media.uploadAll(request);
+        }) ?? {};
+      }
+      const prepare = assertFeishuResponse(await this.withRetry("prepare multipart upload", async () => {
+        const request = {
           data: {
             file_name: fileName,
             parent_type: options.parentType,
             parent_node: options.parentNode,
-            size: buffer.byteLength,
-            extra: options.extra,
-            file: buffer
+            size: buffer.byteLength
           }
-        })) ?? {};
-      }
-      const prepare = assertFeishuResponse(await this.withRetry("prepare multipart upload", async () => this.client.drive.v1.media.uploadPrepare({
-        data: {
-          file_name: fileName,
-          parent_type: options.parentType,
-          parent_node: options.parentNode,
-          size: buffer.byteLength
-        }
-      })), "prepare multipart upload");
+        };
+        return this.client.drive.v1.media.uploadPrepare(this.logRequest("uploadPrepare request", request));
+      }), "prepare multipart upload");
       const uploadId = prepare.data?.upload_id;
       const blockSize = prepare.data?.block_size;
       const blockNum = prepare.data?.block_num;
@@ -476,21 +506,33 @@ class Bitable {
         const start = index * blockSize;
         const end = Math.min(start + blockSize, buffer.byteLength);
         const chunk = buffer.subarray(start, end);
-        await this.withRetry(`upload file chunk ${index + 1}/${blockNum}`, async () => this.client.drive.v1.media.uploadPart({
+        await this.withRetry(`upload file chunk ${index + 1}/${blockNum}`, async () => {
+          const request = {
+            data: {
+              upload_id: uploadId,
+              seq: index,
+              size: chunk.byteLength,
+              file: chunk
+            }
+          };
+          this.logRequest("uploadPart request", {
+            data: {
+              ...request.data,
+              file: `[Buffer ${chunk.byteLength} bytes]`
+            }
+          });
+          return this.client.drive.v1.media.uploadPart(request);
+        });
+      }
+      const finish = assertFeishuResponse(await this.withRetry("finish multipart upload", async () => {
+        const request = {
           data: {
             upload_id: uploadId,
-            seq: index,
-            size: chunk.byteLength,
-            file: chunk
+            block_num: blockNum
           }
-        }));
-      }
-      const finish = assertFeishuResponse(await this.withRetry("finish multipart upload", async () => this.client.drive.v1.media.uploadFinish({
-        data: {
-          upload_id: uploadId,
-          block_num: blockNum
-        }
-      })), "finish multipart upload");
+        };
+        return this.client.drive.v1.media.uploadFinish(this.logRequest("uploadFinish request", request));
+      }), "finish multipart upload");
       return {
         file_token: finish.data?.file_token
       };
@@ -501,14 +543,17 @@ class Bitable {
       fileToken,
       hasExtra: Boolean(extra)
     }, async () => {
-      const response = await this.withRetry("download file", async () => this.client.drive.v1.media.download({
-        path: {
-          file_token: fileToken
-        },
-        params: {
-          extra
-        }
-      }));
+      const response = await this.withRetry("download file", async () => {
+        const request = {
+          path: {
+            file_token: fileToken
+          },
+          params: {
+            extra
+          }
+        };
+        return this.client.drive.v1.media.download(this.logRequest("downloadFile request", request));
+      });
       const buffer = await readableToBuffer(response.getReadableStream());
       this.logInfo("downloadFile completed", {
         fileToken,
@@ -550,7 +595,7 @@ class Bitable {
     return token;
   }
   async executeBatchUpdateRecords(payload) {
-    return this.withRetry("batch update records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchUpdate(payload), "batch update records"));
+    return this.withRetry("batch update records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchUpdate(this.logRequest("batchUpdateRecords request", payload)), "batch update records"));
   }
   async withRetry(label, task) {
     let lastError;
@@ -623,6 +668,189 @@ class Bitable {
       errorMessage: String(error)
     };
   }
+  logRequest(message, payload) {
+    this.logInfo(message, {
+      payload
+    });
+    return payload;
+  }
+}
+
+// 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

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

@@ -211,7 +211,7 @@ class Bitable {
     }, async () => {
       const token = this.resolveAppToken(appToken);
       const pageSize = Math.max(1, Math.min(options.pageSize ?? FEISHU_BATCH_LIMIT, FEISHU_BATCH_LIMIT));
-      const iterator = await this.client.bitable.v1.appTableRecord.searchWithIterator({
+      const request = {
         path: {
           app_token: token,
           table_id: tableId
@@ -227,7 +227,8 @@ class Bitable {
           sort: options.sort,
           automatic_fields: options.automaticFields
         }
-      });
+      };
+      const iterator = await this.client.bitable.v1.appTableRecord.searchWithIterator(this.logRequest("fetchAllRecords request", request));
       const allRecords = [];
       for await (const page of iterator) {
         const items = page?.items ?? [];
@@ -252,12 +253,15 @@ class Bitable {
       }
       const token = this.resolveAppToken(options.appToken);
       const chunks = chunkArray(records, options.chunkSize ?? FEISHU_BATCH_LIMIT);
-      const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => this.withRetry("insert records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchCreate({
-        path: { app_token: token, table_id: tableId },
-        data: {
-          records: chunk.map((fields) => ({ fields }))
-        }
-      }), "insert records")));
+      const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => this.withRetry("insert records", async () => {
+        const request = {
+          path: { app_token: token, table_id: tableId },
+          data: {
+            records: chunk.map((fields) => ({ fields }))
+          }
+        };
+        return assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchCreate(this.logRequest("insertList request", request)), "insert records");
+      }));
       this.logInfo("insertList completed", {
         tableId,
         chunkCount: chunks.length
@@ -284,8 +288,18 @@ class Bitable {
       const token = this.resolveAppToken(options.appToken);
       const chunks = chunkArray(records, options.chunkSize ?? FEISHU_BATCH_LIMIT);
       const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk, index) => {
-        const batchRecords = chunk.map((record) => {
+        const batchRecords = chunk.map((record, recordIndex) => {
           const { recordId, fields } = splitUpdateRecord(record);
+          if (!recordId || !recordId.trim()) {
+            throw new FeishuBitableError(`updateRecords failed: record_id is required for chunk ${index}, item ${recordIndex}`, {
+              details: {
+                tableId,
+                chunkIndex: index,
+                recordIndex,
+                record
+              }
+            });
+          }
           if (Object.keys(fields).length === 0) {
             return null;
           }
@@ -344,12 +358,15 @@ class Bitable {
       }
       const token = this.resolveAppToken(options.appToken);
       const chunks = chunkArray(recordIds, options.chunkSize ?? FEISHU_BATCH_LIMIT);
-      const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => this.withRetry("delete records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchDelete({
-        path: { app_token: token, table_id: tableId },
-        data: {
-          records: chunk
-        }
-      }), "delete records")));
+      const responses = await runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => this.withRetry("delete records", async () => {
+        const request = {
+          path: { app_token: token, table_id: tableId },
+          data: {
+            records: chunk
+          }
+        };
+        return assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchDelete(this.logRequest("deleteList request", request)), "delete records");
+      }));
       this.logInfo("deleteList completed", {
         tableId,
         chunkCount: chunks.length
@@ -371,25 +388,37 @@ class Bitable {
         mode: buffer.byteLength <= FEISHU_SIMPLE_UPLOAD_LIMIT ? "simple" : "multipart"
       });
       if (buffer.byteLength <= FEISHU_SIMPLE_UPLOAD_LIMIT) {
-        return await this.withRetry("upload file", async () => this.client.drive.v1.media.uploadAll({
+        return await this.withRetry("upload file", async () => {
+          const request = {
+            data: {
+              file_name: fileName,
+              parent_type: options.parentType,
+              parent_node: options.parentNode,
+              size: buffer.byteLength,
+              extra: options.extra,
+              file: buffer
+            }
+          };
+          this.logRequest("uploadFile request", {
+            data: {
+              ...request.data,
+              file: `[Buffer ${buffer.byteLength} bytes]`
+            }
+          });
+          return this.client.drive.v1.media.uploadAll(request);
+        }) ?? {};
+      }
+      const prepare = assertFeishuResponse(await this.withRetry("prepare multipart upload", async () => {
+        const request = {
           data: {
             file_name: fileName,
             parent_type: options.parentType,
             parent_node: options.parentNode,
-            size: buffer.byteLength,
-            extra: options.extra,
-            file: buffer
+            size: buffer.byteLength
           }
-        })) ?? {};
-      }
-      const prepare = assertFeishuResponse(await this.withRetry("prepare multipart upload", async () => this.client.drive.v1.media.uploadPrepare({
-        data: {
-          file_name: fileName,
-          parent_type: options.parentType,
-          parent_node: options.parentNode,
-          size: buffer.byteLength
-        }
-      })), "prepare multipart upload");
+        };
+        return this.client.drive.v1.media.uploadPrepare(this.logRequest("uploadPrepare request", request));
+      }), "prepare multipart upload");
       const uploadId = prepare.data?.upload_id;
       const blockSize = prepare.data?.block_size;
       const blockNum = prepare.data?.block_num;
@@ -402,21 +431,33 @@ class Bitable {
         const start = index * blockSize;
         const end = Math.min(start + blockSize, buffer.byteLength);
         const chunk = buffer.subarray(start, end);
-        await this.withRetry(`upload file chunk ${index + 1}/${blockNum}`, async () => this.client.drive.v1.media.uploadPart({
+        await this.withRetry(`upload file chunk ${index + 1}/${blockNum}`, async () => {
+          const request = {
+            data: {
+              upload_id: uploadId,
+              seq: index,
+              size: chunk.byteLength,
+              file: chunk
+            }
+          };
+          this.logRequest("uploadPart request", {
+            data: {
+              ...request.data,
+              file: `[Buffer ${chunk.byteLength} bytes]`
+            }
+          });
+          return this.client.drive.v1.media.uploadPart(request);
+        });
+      }
+      const finish = assertFeishuResponse(await this.withRetry("finish multipart upload", async () => {
+        const request = {
           data: {
             upload_id: uploadId,
-            seq: index,
-            size: chunk.byteLength,
-            file: chunk
+            block_num: blockNum
           }
-        }));
-      }
-      const finish = assertFeishuResponse(await this.withRetry("finish multipart upload", async () => this.client.drive.v1.media.uploadFinish({
-        data: {
-          upload_id: uploadId,
-          block_num: blockNum
-        }
-      })), "finish multipart upload");
+        };
+        return this.client.drive.v1.media.uploadFinish(this.logRequest("uploadFinish request", request));
+      }), "finish multipart upload");
       return {
         file_token: finish.data?.file_token
       };
@@ -427,14 +468,17 @@ class Bitable {
       fileToken,
       hasExtra: Boolean(extra)
     }, async () => {
-      const response = await this.withRetry("download file", async () => this.client.drive.v1.media.download({
-        path: {
-          file_token: fileToken
-        },
-        params: {
-          extra
-        }
-      }));
+      const response = await this.withRetry("download file", async () => {
+        const request = {
+          path: {
+            file_token: fileToken
+          },
+          params: {
+            extra
+          }
+        };
+        return this.client.drive.v1.media.download(this.logRequest("downloadFile request", request));
+      });
       const buffer = await readableToBuffer(response.getReadableStream());
       this.logInfo("downloadFile completed", {
         fileToken,
@@ -476,7 +520,7 @@ class Bitable {
     return token;
   }
   async executeBatchUpdateRecords(payload) {
-    return this.withRetry("batch update records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchUpdate(payload), "batch update records"));
+    return this.withRetry("batch update records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchUpdate(this.logRequest("batchUpdateRecords request", payload)), "batch update records"));
   }
   async withRetry(label, task) {
     let lastError;
@@ -549,16 +593,200 @@ class Bitable {
       errorMessage: String(error)
     };
   }
+  logRequest(message, payload) {
+    this.logInfo(message, {
+      payload
+    });
+    return payload;
+  }
+}
+
+// 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.3",
+  "version": "0.0.5",
   "description": "基于 Bun + TypeScript + 飞书官方 SDK 的多维表格操作库",
   "type": "module",
   "main": "./lib/index.cjs",