@yuuko1410/feishu-bitable 0.0.2 → 0.0.4

package/lib/index.js

@@ -96,7 +96,8 @@ function normalizeRecordFields(fields) {
 }
 function splitUpdateRecord(record) {
   const { record_id: recordId, ...fields } = record;
-  return { recordId, fields };
+  const normalizedFields = Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+  return { recordId, fields: normalizedFields };
 }
 async function toBuffer(file) {
   if (typeof file === "string") {
@@ -149,18 +150,44 @@ function isFileLike(value) {
 }
 
 // src/client.ts
+var DEFAULT_LOGGER = {
+  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 Bitable {
   client;
   defaultAppToken;
   maxRetries;
   retryDelayMs;
   defaultConcurrency;
+  logger;
   constructor(optionsOrToken, appId, appSecret) {
     const options = this.resolveConstructorOptions(optionsOrToken, appId, appSecret);
     this.defaultAppToken = options.defaultAppToken;
     this.maxRetries = Math.max(1, options.maxRetries ?? 5);
     this.retryDelayMs = Math.max(100, options.retryDelayMs ?? 1000);
     this.defaultConcurrency = Math.max(1, options.defaultConcurrency ?? 1);
+    this.logger = options.logger === null ? null : options.logger ?? DEFAULT_LOGGER;
     this.client = options.sdkClient ?? new lark.Client({
       appId: options.appId,
       appSecret: options.appSecret,
@@ -176,159 +203,295 @@ class Bitable {
     });
   }
   async fetchAllRecords(tableId, options = {}, appToken) {
-    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({
-      path: {
-        app_token: token,
-        table_id: tableId
-      },
-      params: {
-        page_size: pageSize,
-        user_id_type: "open_id"
-      },
-      data: {
-        view_id: options.viewId,
-        field_names: options.fieldNames,
-        filter: options.filter,
-        sort: options.sort,
-        automatic_fields: options.automaticFields
+    return this.runLogged("fetchAllRecords", {
+      tableId,
+      pageSize: options.pageSize ?? FEISHU_BATCH_LIMIT,
+      hasViewId: Boolean(options.viewId),
+      fieldCount: options.fieldNames?.length ?? 0
+    }, async () => {
+      const token = this.resolveAppToken(appToken);
+      const pageSize = Math.max(1, Math.min(options.pageSize ?? FEISHU_BATCH_LIMIT, FEISHU_BATCH_LIMIT));
+      const request = {
+        path: {
+          app_token: token,
+          table_id: tableId
+        },
+        params: {
+          page_size: pageSize,
+          user_id_type: "open_id"
+        },
+        data: {
+          view_id: options.viewId,
+          field_names: options.fieldNames,
+          filter: options.filter,
+          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 ?? [];
+        allRecords.push(...items.map((item) => normalizeRecord(item.record_id, item.fields, options.normalizeFields !== false)));
       }
+      this.logInfo("fetchAllRecords completed", {
+        tableId,
+        recordCount: allRecords.length
+      });
+      return allRecords;
     });
-    const allRecords = [];
-    for await (const page of iterator) {
-      const items = page?.items ?? [];
-      allRecords.push(...items.map((item) => normalizeRecord(item.record_id, item.fields, options.normalizeFields !== false)));
-    }
-    return allRecords;
   }
   async insertList(tableId, records, options = {}) {
-    if (records.length === 0) {
-      return [];
-    }
-    const token = this.resolveAppToken(options.appToken);
-    const chunks = chunkArray(records, options.chunkSize ?? FEISHU_BATCH_LIMIT);
-    return 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 }))
+    return this.runLogged("insertList", {
+      tableId,
+      recordCount: records.length,
+      chunkSize: options.chunkSize ?? FEISHU_BATCH_LIMIT,
+      concurrency: options.concurrency ?? this.defaultConcurrency
+    }, async () => {
+      if (records.length === 0) {
+        return [];
       }
-    }), "insert records")));
+      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 () => {
+        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
+      });
+      return responses;
+    });
   }
   async batchUpdateRecords(payload) {
-    return this.withRetry("batch update records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchUpdate(payload), "batch update records"));
+    return this.runLogged("batchUpdateRecords", {
+      tableId: payload.path.table_id,
+      recordCount: payload.data.records.length
+    }, async () => this.executeBatchUpdateRecords(payload));
   }
   async updateRecords(tableId, records, options = {}) {
-    if (records.length === 0) {
-      return [];
-    }
-    const token = this.resolveAppToken(options.appToken);
-    const chunks = chunkArray(records, options.chunkSize ?? FEISHU_BATCH_LIMIT);
-    return runWithConcurrency(chunks, options.concurrency ?? this.defaultConcurrency, async (chunk) => {
-      const payload = {
-        path: {
-          app_token: token,
-          table_id: tableId
-        },
-        data: {
-          records: chunk.map((record) => {
-            const { recordId, fields } = splitUpdateRecord(record);
-            return {
-              record_id: recordId,
-              fields
-            };
-          })
+    return this.runLogged("updateRecords", {
+      tableId,
+      inputRecordCount: records.length,
+      chunkSize: options.chunkSize ?? FEISHU_BATCH_LIMIT,
+      concurrency: options.concurrency ?? this.defaultConcurrency
+    }, async () => {
+      if (records.length === 0) {
+        return [];
+      }
+      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, 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;
+          }
+          return {
+            record_id: recordId,
+            fields
+          };
+        }).filter((record) => Boolean(record));
+        if (batchRecords.length === 0) {
+          this.logInfo("updateRecords skipped empty chunk", {
+            tableId,
+            chunkIndex: index,
+            inputChunkSize: chunk.length
+          });
+          return {
+            code: 0,
+            msg: "ok",
+            data: {
+              records: []
+            }
+          };
         }
-      };
-      if (options.userIdType || options.ignoreConsistencyCheck !== undefined) {
-        payload.params = {
-          user_id_type: options.userIdType,
-          ignore_consistency_check: options.ignoreConsistencyCheck
+        const payload = {
+          path: {
+            app_token: token,
+            table_id: tableId
+          },
+          data: {
+            records: batchRecords
+          }
         };
-      }
-      return this.batchUpdateRecords(payload);
+        if (options.userIdType || options.ignoreConsistencyCheck !== undefined) {
+          payload.params = {
+            user_id_type: options.userIdType,
+            ignore_consistency_check: options.ignoreConsistencyCheck
+          };
+        }
+        return this.executeBatchUpdateRecords(payload);
+      });
+      this.logInfo("updateRecords completed", {
+        tableId,
+        chunkCount: chunks.length
+      });
+      return responses;
     });
   }
   async deleteList(tableId, recordIds, options = {}) {
-    if (recordIds.length === 0) {
-      return [];
-    }
-    const token = this.resolveAppToken(options.appToken);
-    const chunks = chunkArray(recordIds, options.chunkSize ?? FEISHU_BATCH_LIMIT);
-    return 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
+    return this.runLogged("deleteList", {
+      tableId,
+      recordCount: recordIds.length,
+      chunkSize: options.chunkSize ?? FEISHU_BATCH_LIMIT,
+      concurrency: options.concurrency ?? this.defaultConcurrency
+    }, async () => {
+      if (recordIds.length === 0) {
+        return [];
       }
-    }), "delete records")));
+      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 () => {
+        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
+      });
+      return responses;
+    });
   }
   async uploadFile(options) {
-    const buffer = await toBuffer(options.file);
-    const fileName = options.fileName ?? inferFileName(options.file);
-    if (buffer.byteLength <= FEISHU_SIMPLE_UPLOAD_LIMIT) {
-      return await this.withRetry("upload file", async () => this.client.drive.v1.media.uploadAll({
-        data: {
-          file_name: fileName,
-          parent_type: options.parentType,
-          parent_node: options.parentNode,
-          size: buffer.byteLength,
-          extra: options.extra,
-          file: buffer
-        }
-      })) ?? {};
-    }
-    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");
-    const uploadId = prepare.data?.upload_id;
-    const blockSize = prepare.data?.block_size;
-    const blockNum = prepare.data?.block_num;
-    if (!uploadId || !blockSize || !blockNum) {
-      throw new FeishuBitableError("prepare multipart upload failed: missing upload metadata", {
-        details: prepare
+    return this.runLogged("uploadFile", {
+      parentType: options.parentType,
+      parentNode: options.parentNode,
+      hasExtra: Boolean(options.extra)
+    }, async () => {
+      const buffer = await toBuffer(options.file);
+      const fileName = options.fileName ?? inferFileName(options.file);
+      this.logInfo("uploadFile resolved input", {
+        fileName,
+        size: buffer.byteLength,
+        mode: buffer.byteLength <= FEISHU_SIMPLE_UPLOAD_LIMIT ? "simple" : "multipart"
       });
-    }
-    for (let index = 0;index < blockNum; index++) {
-      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({
-        data: {
-          upload_id: uploadId,
-          seq: index,
-          size: chunk.byteLength,
-          file: chunk
-        }
-      }));
-    }
-    const finish = assertFeishuResponse(await this.withRetry("finish multipart upload", async () => this.client.drive.v1.media.uploadFinish({
-      data: {
-        upload_id: uploadId,
-        block_num: blockNum
+      if (buffer.byteLength <= FEISHU_SIMPLE_UPLOAD_LIMIT) {
+        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);
+        }) ?? {};
       }
-    })), "finish multipart upload");
-    return {
-      file_token: finish.data?.file_token
-    };
+      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
+          }
+        };
+        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;
+      if (!uploadId || !blockSize || !blockNum) {
+        throw new FeishuBitableError("prepare multipart upload failed: missing upload metadata", {
+          details: prepare
+        });
+      }
+      for (let index = 0;index < blockNum; index++) {
+        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 () => {
+          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,
+            block_num: blockNum
+          }
+        };
+        return this.client.drive.v1.media.uploadFinish(this.logRequest("uploadFinish request", request));
+      }), "finish multipart upload");
+      return {
+        file_token: finish.data?.file_token
+      };
+    });
   }
   async downloadFile(fileToken, extra) {
-    const response = await this.withRetry("download file", async () => this.client.drive.v1.media.download({
-      path: {
-        file_token: fileToken
-      },
-      params: {
-        extra
-      }
-    }));
-    return readableToBuffer(response.getReadableStream());
+    return this.runLogged("downloadFile", {
+      fileToken,
+      hasExtra: Boolean(extra)
+    }, async () => {
+      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,
+        size: buffer.byteLength
+      });
+      return buffer;
+    });
   }
   async downLoadFile(fileToken, extra) {
-    return this.downloadFile(fileToken, extra);
+    return this.runLogged("downLoadFile", {
+      fileToken,
+      hasExtra: Boolean(extra)
+    }, async () => this.downloadFile(fileToken, extra));
   }
   resolveConstructorOptions(optionsOrToken, appIdArg, appSecretArg) {
     const objectMode = typeof optionsOrToken === "object" && optionsOrToken !== null && !Array.isArray(optionsOrToken);
@@ -356,6 +519,9 @@ class Bitable {
     }
     return token;
   }
+  async executeBatchUpdateRecords(payload) {
+    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;
     for (let attempt = 1;attempt <= this.maxRetries; attempt++) {
@@ -363,15 +529,75 @@ class Bitable {
         return await task();
       } catch (error) {
         lastError = error;
+        const meta = {
+          label,
+          attempt,
+          maxRetries: this.maxRetries,
+          retryDelayMs: this.retryDelayMs,
+          ...this.getErrorMeta(error)
+        };
         if (attempt === this.maxRetries) {
+          this.logError("request exhausted retries", meta);
           break;
         }
+        this.logWarn("request attempt failed, retrying", meta);
         await sleep(this.retryDelayMs * attempt);
       }
     }
-    throw new FeishuBitableError(`${label} failed after ${this.maxRetries} attempts`, {
-      cause: lastError
+    const causeMessage = lastError instanceof Error ? `: ${lastError.message}` : "";
+    throw new FeishuBitableError(`${label} failed after ${this.maxRetries} attempts${causeMessage}`, {
+      cause: lastError,
+      code: lastError instanceof FeishuBitableError ? lastError.code : undefined,
+      details: lastError instanceof FeishuBitableError ? lastError.details : undefined
+    });
+  }
+  async runLogged(action, meta, task) {
+    this.logInfo(`${action} started`, meta);
+    try {
+      const result = await task();
+      this.logInfo(`${action} succeeded`, meta);
+      return result;
+    } catch (error) {
+      this.logError(`${action} failed`, {
+        ...meta,
+        ...this.getErrorMeta(error)
+      });
+      throw error;
+    }
+  }
+  logInfo(message, meta) {
+    this.logger?.info(message, meta);
+  }
+  logWarn(message, meta) {
+    this.logger?.warn?.(message, meta);
+  }
+  logError(message, meta) {
+    this.logger?.error?.(message, meta);
+  }
+  getErrorMeta(error) {
+    if (error instanceof FeishuBitableError) {
+      return {
+        errorName: error.name,
+        errorMessage: error.message,
+        errorCode: error.code,
+        errorDetails: error.details
+      };
+    }
+    if (error instanceof Error) {
+      return {
+        errorName: error.name,
+        errorMessage: error.message
+      };
+    }
+    return {
+      errorMessage: String(error)
+    };
+  }
+  logRequest(message, payload) {
+    this.logInfo(message, {
+      payload
     });
+    return payload;
   }
 }
 

package/lib/types.d.ts

@@ -62,6 +62,11 @@ export type BitableFilterGroup = {
 };
 export type MediaParentType = "doc_image" | "docx_image" | "sheet_image" | "doc_file" | "docx_file" | "sheet_file" | "vc_virtual_background" | "bitable_image" | "bitable_file" | "moments" | "ccm_import_open" | "calendar" | "base_global" | "lark_ai_media_analysis";
 export type UploadableFile = string | Buffer | Uint8Array | ArrayBuffer | Blob | BunFileLike;
+export type BitableLogger = {
+    info: (message: string, meta?: Record<string, unknown>) => void;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    error?: (message: string, meta?: Record<string, unknown>) => void;
+};
 export type BunFileLike = {
     arrayBuffer(): Promise<ArrayBuffer>;
     name?: string;
@@ -76,6 +81,7 @@ export interface BitableConstructorOptions {
     retryDelayMs?: number;
     defaultConcurrency?: number;
     sdkClient?: lark.Client;
+    logger?: BitableLogger | null;
 }
 export interface FetchAllRecordsOptions {
     viewId?: string;

package/package.json

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