@yuuko1410/feishu-bitable 0.0.2

package/lib/client.d.ts

@@ -0,0 +1,33 @@
+import * as lark from "@larksuiteoapi/node-sdk";
+import type { BatchOperationOptions, BitableBatchUpdatePayload, BitableBatchUpdateResponse, BitableConstructorOptions, BitableInsertRecord, BitableRecord, BitableUpdateRecord, FetchAllRecordsOptions, UpdateRecordsOptions, UploadFileOptions } from "./types";
+export declare class Bitable {
+    readonly client: lark.Client;
+    readonly defaultAppToken?: string;
+    readonly maxRetries: number;
+    readonly retryDelayMs: number;
+    readonly defaultConcurrency: number;
+    constructor(options?: BitableConstructorOptions);
+    constructor(defaultAppToken?: string | null, appId?: string | null, appSecret?: string | null);
+    static fromEnv(env?: NodeJS.ProcessEnv): Bitable;
+    fetchAllRecords(tableId: string, options?: FetchAllRecordsOptions, appToken?: string): Promise<BitableRecord[]>;
+    insertList(tableId: string, records: BitableInsertRecord[], options?: BatchOperationOptions): Promise<Array<{
+        code?: number;
+        msg?: string;
+        data?: unknown;
+    }>>;
+    batchUpdateRecords(payload: BitableBatchUpdatePayload): Promise<BitableBatchUpdateResponse>;
+    updateRecords(tableId: string, records: BitableUpdateRecord[], options?: UpdateRecordsOptions): Promise<BitableBatchUpdateResponse[]>;
+    deleteList(tableId: string, recordIds: string[], options?: BatchOperationOptions): Promise<Array<{
+        code?: number;
+        msg?: string;
+        data?: unknown;
+    }>>;
+    uploadFile(options: UploadFileOptions): Promise<{
+        file_token?: string;
+    }>;
+    downloadFile(fileToken: string, extra?: string): Promise<Buffer>;
+    downLoadFile(fileToken: string, extra?: string): Promise<Buffer>;
+    private resolveConstructorOptions;
+    private resolveAppToken;
+    private withRetry;
+}

package/lib/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class FeishuBitableError extends Error {
+    readonly code?: number;
+    readonly details?: unknown;
+    constructor(message: string, options?: {
+        code?: number;
+        details?: unknown;
+        cause?: unknown;
+    });
+}

package/lib/index.cjs

@@ -0,0 +1,454 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  default: () => src_default,
+  LoggerLevel: () => import_node_sdk.LoggerLevel,
+  FeishuBitableError: () => FeishuBitableError,
+  Domain: () => import_node_sdk.Domain,
+  Bitable: () => Bitable,
+  AppType: () => import_node_sdk.AppType
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/client.ts
+var lark = __toESM(require("@larksuiteoapi/node-sdk"));
+
+// src/errors.ts
+class FeishuBitableError extends Error {
+  code;
+  details;
+  constructor(message, options) {
+    super(message, options?.cause ? { cause: options.cause } : undefined);
+    this.name = "FeishuBitableError";
+    this.code = options?.code;
+    this.details = options?.details;
+  }
+}
+
+// src/utils.ts
+var DATA_URL_PATTERN = /^data:([A-Za-z-+/]+\/[A-Za-z0-9.+-]+)?;base64,(.+)$/;
+var MIME_EXTENSION_MAP = {
+  "image/jpeg": "jpg",
+  "image/jpg": "jpg",
+  "image/png": "png",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "application/pdf": "pdf",
+  "text/plain": "txt"
+};
+var FEISHU_BATCH_LIMIT = 500;
+var FEISHU_SIMPLE_UPLOAD_LIMIT = 20 * 1024 * 1024;
+function chunkArray(items, chunkSize) {
+  const normalizedChunkSize = Math.max(1, Math.min(chunkSize, FEISHU_BATCH_LIMIT));
+  const chunks = [];
+  for (let index = 0;index < items.length; index += normalizedChunkSize) {
+    chunks.push(items.slice(index, index + normalizedChunkSize));
+  }
+  return chunks;
+}
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runWithConcurrency(items, concurrency, worker) {
+  const results = new Array(items.length);
+  const normalizedConcurrency = Math.max(1, concurrency);
+  let cursor = 0;
+  async function runWorker() {
+    while (true) {
+      const index = cursor++;
+      if (index >= items.length) {
+        return;
+      }
+      results[index] = await worker(items[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(normalizedConcurrency, items.length) }, () => runWorker()));
+  return results;
+}
+function assertFeishuResponse(response, action) {
+  if (!response) {
+    throw new FeishuBitableError(`${action} failed: empty response from Feishu SDK`);
+  }
+  if (typeof response.code === "number" && response.code !== 0) {
+    throw new FeishuBitableError(`${action} failed: ${response.msg ?? "unknown error"}`, {
+      code: response.code,
+      details: response
+    });
+  }
+  return response;
+}
+function normalizeFieldValue(value) {
+  if (Array.isArray(value)) {
+    if (value.length === 1 && isPlainObject(value[0]) && typeof value[0].text === "string") {
+      return value[0].text;
+    }
+    return value;
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  if (typeof value.type === "number" && "value" in value) {
+    if (value.type === 1 && Array.isArray(value.value)) {
+      return value.value.map((item) => isPlainObject(item) && typeof item.text === "string" ? item.text : String(item ?? "")).join("");
+    }
+    if ((value.type === 2 || value.type === 3 || value.type === 1005) && Array.isArray(value.value)) {
+      return value.value.join(",");
+    }
+  }
+  return value;
+}
+function normalizeRecord(recordId, fields, normalizeFields = true) {
+  return {
+    ...normalizeFields ? normalizeRecordFields(fields) : fields,
+    record_id: recordId ?? ""
+  };
+}
+function normalizeRecordFields(fields) {
+  return Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, normalizeFieldValue(value)]));
+}
+function splitUpdateRecord(record) {
+  const { record_id: recordId, ...fields } = record;
+  return { recordId, fields };
+}
+async function toBuffer(file) {
+  if (typeof file === "string") {
+    const dataUrlMatch = file.match(DATA_URL_PATTERN);
+    const base64Payload = dataUrlMatch ? dataUrlMatch[2] : file;
+    return Buffer.from(base64Payload, "base64");
+  }
+  if (Buffer.isBuffer(file)) {
+    return file;
+  }
+  if (file instanceof Uint8Array) {
+    return Buffer.from(file);
+  }
+  if (file instanceof ArrayBuffer) {
+    return Buffer.from(file);
+  }
+  if (typeof Blob !== "undefined" && file instanceof Blob) {
+    return Buffer.from(await file.arrayBuffer());
+  }
+  if (isFileLike(file)) {
+    return Buffer.from(await file.arrayBuffer());
+  }
+  throw new FeishuBitableError("Unsupported file input. Use base64 string, Buffer, Uint8Array, ArrayBuffer, Blob or Bun.file().");
+}
+function inferFileName(file, fallback = "upload.bin") {
+  if (isFileLike(file) && typeof file.name === "string" && file.name.trim()) {
+    return file.name;
+  }
+  if (typeof file === "string") {
+    const dataUrlMatch = file.match(DATA_URL_PATTERN);
+    const mimeType = dataUrlMatch?.[1];
+    if (mimeType && MIME_EXTENSION_MAP[mimeType]) {
+      return `upload.${MIME_EXTENSION_MAP[mimeType]}`;
+    }
+  }
+  return fallback;
+}
+async function readableToBuffer(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFileLike(value) {
+  return isPlainObject(value) && typeof value.arrayBuffer === "function";
+}
+
+// src/client.ts
+class Bitable {
+  client;
+  defaultAppToken;
+  maxRetries;
+  retryDelayMs;
+  defaultConcurrency;
+  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.client = options.sdkClient ?? new lark.Client({
+      appId: options.appId,
+      appSecret: options.appSecret,
+      appType: options.appType ?? lark.AppType.SelfBuild,
+      domain: options.domain ?? lark.Domain.Feishu
+    });
+  }
+  static fromEnv(env = process.env) {
+    return new Bitable({
+      appId: env.FEISHU_APP_ID,
+      appSecret: env.FEISHU_APP_SECRET,
+      defaultAppToken: env.FEISHU_APP_TOKEN
+    });
+  }
+  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
+      }
+    });
+    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 }))
+      }
+    }), "insert records")));
+  }
+  async batchUpdateRecords(payload) {
+    return this.withRetry("batch update records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchUpdate(payload), "batch update records"));
+  }
+  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
+            };
+          })
+        }
+      };
+      if (options.userIdType || options.ignoreConsistencyCheck !== undefined) {
+        payload.params = {
+          user_id_type: options.userIdType,
+          ignore_consistency_check: options.ignoreConsistencyCheck
+        };
+      }
+      return this.batchUpdateRecords(payload);
+    });
+  }
+  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
+      }
+    }), "delete records")));
+  }
+  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
+      });
+    }
+    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
+      }
+    })), "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());
+  }
+  async downLoadFile(fileToken, extra) {
+    return this.downloadFile(fileToken, extra);
+  }
+  resolveConstructorOptions(optionsOrToken, appIdArg, appSecretArg) {
+    const objectMode = typeof optionsOrToken === "object" && optionsOrToken !== null && !Array.isArray(optionsOrToken);
+    const options = objectMode ? optionsOrToken : {
+      defaultAppToken: typeof optionsOrToken === "string" ? optionsOrToken : undefined,
+      appId: appIdArg ?? undefined,
+      appSecret: appSecretArg ?? undefined
+    };
+    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 the constructor or provide FEISHU_APP_ID and FEISHU_APP_SECRET.");
+    }
+    return {
+      ...options,
+      appId,
+      appSecret,
+      defaultAppToken: options.defaultAppToken ?? process.env.FEISHU_APP_TOKEN
+    };
+  }
+  resolveAppToken(overrideToken) {
+    const token = overrideToken ?? this.defaultAppToken;
+    if (!token) {
+      throw new FeishuBitableError("appToken is required. Pass it to the constructor, method options, or FEISHU_APP_TOKEN.");
+    }
+    return token;
+  }
+  async withRetry(label, task) {
+    let lastError;
+    for (let attempt = 1;attempt <= this.maxRetries; attempt++) {
+      try {
+        return await task();
+      } catch (error) {
+        lastError = error;
+        if (attempt === this.maxRetries) {
+          break;
+        }
+        await sleep(this.retryDelayMs * attempt);
+      }
+    }
+    throw new FeishuBitableError(`${label} failed after ${this.maxRetries} attempts`, {
+      cause: lastError
+    });
+  }
+}
+
+// src/index.ts
+var import_node_sdk = require("@larksuiteoapi/node-sdk");
+var src_default = Bitable;

package/lib/index.d.ts

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

package/lib/index.js

@@ -0,0 +1,388 @@
+// src/client.ts
+import * as lark from "@larksuiteoapi/node-sdk";
+
+// src/errors.ts
+class FeishuBitableError extends Error {
+  code;
+  details;
+  constructor(message, options) {
+    super(message, options?.cause ? { cause: options.cause } : undefined);
+    this.name = "FeishuBitableError";
+    this.code = options?.code;
+    this.details = options?.details;
+  }
+}
+
+// src/utils.ts
+var DATA_URL_PATTERN = /^data:([A-Za-z-+/]+\/[A-Za-z0-9.+-]+)?;base64,(.+)$/;
+var MIME_EXTENSION_MAP = {
+  "image/jpeg": "jpg",
+  "image/jpg": "jpg",
+  "image/png": "png",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "application/pdf": "pdf",
+  "text/plain": "txt"
+};
+var FEISHU_BATCH_LIMIT = 500;
+var FEISHU_SIMPLE_UPLOAD_LIMIT = 20 * 1024 * 1024;
+function chunkArray(items, chunkSize) {
+  const normalizedChunkSize = Math.max(1, Math.min(chunkSize, FEISHU_BATCH_LIMIT));
+  const chunks = [];
+  for (let index = 0;index < items.length; index += normalizedChunkSize) {
+    chunks.push(items.slice(index, index + normalizedChunkSize));
+  }
+  return chunks;
+}
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runWithConcurrency(items, concurrency, worker) {
+  const results = new Array(items.length);
+  const normalizedConcurrency = Math.max(1, concurrency);
+  let cursor = 0;
+  async function runWorker() {
+    while (true) {
+      const index = cursor++;
+      if (index >= items.length) {
+        return;
+      }
+      results[index] = await worker(items[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(normalizedConcurrency, items.length) }, () => runWorker()));
+  return results;
+}
+function assertFeishuResponse(response, action) {
+  if (!response) {
+    throw new FeishuBitableError(`${action} failed: empty response from Feishu SDK`);
+  }
+  if (typeof response.code === "number" && response.code !== 0) {
+    throw new FeishuBitableError(`${action} failed: ${response.msg ?? "unknown error"}`, {
+      code: response.code,
+      details: response
+    });
+  }
+  return response;
+}
+function normalizeFieldValue(value) {
+  if (Array.isArray(value)) {
+    if (value.length === 1 && isPlainObject(value[0]) && typeof value[0].text === "string") {
+      return value[0].text;
+    }
+    return value;
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  if (typeof value.type === "number" && "value" in value) {
+    if (value.type === 1 && Array.isArray(value.value)) {
+      return value.value.map((item) => isPlainObject(item) && typeof item.text === "string" ? item.text : String(item ?? "")).join("");
+    }
+    if ((value.type === 2 || value.type === 3 || value.type === 1005) && Array.isArray(value.value)) {
+      return value.value.join(",");
+    }
+  }
+  return value;
+}
+function normalizeRecord(recordId, fields, normalizeFields = true) {
+  return {
+    ...normalizeFields ? normalizeRecordFields(fields) : fields,
+    record_id: recordId ?? ""
+  };
+}
+function normalizeRecordFields(fields) {
+  return Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, normalizeFieldValue(value)]));
+}
+function splitUpdateRecord(record) {
+  const { record_id: recordId, ...fields } = record;
+  return { recordId, fields };
+}
+async function toBuffer(file) {
+  if (typeof file === "string") {
+    const dataUrlMatch = file.match(DATA_URL_PATTERN);
+    const base64Payload = dataUrlMatch ? dataUrlMatch[2] : file;
+    return Buffer.from(base64Payload, "base64");
+  }
+  if (Buffer.isBuffer(file)) {
+    return file;
+  }
+  if (file instanceof Uint8Array) {
+    return Buffer.from(file);
+  }
+  if (file instanceof ArrayBuffer) {
+    return Buffer.from(file);
+  }
+  if (typeof Blob !== "undefined" && file instanceof Blob) {
+    return Buffer.from(await file.arrayBuffer());
+  }
+  if (isFileLike(file)) {
+    return Buffer.from(await file.arrayBuffer());
+  }
+  throw new FeishuBitableError("Unsupported file input. Use base64 string, Buffer, Uint8Array, ArrayBuffer, Blob or Bun.file().");
+}
+function inferFileName(file, fallback = "upload.bin") {
+  if (isFileLike(file) && typeof file.name === "string" && file.name.trim()) {
+    return file.name;
+  }
+  if (typeof file === "string") {
+    const dataUrlMatch = file.match(DATA_URL_PATTERN);
+    const mimeType = dataUrlMatch?.[1];
+    if (mimeType && MIME_EXTENSION_MAP[mimeType]) {
+      return `upload.${MIME_EXTENSION_MAP[mimeType]}`;
+    }
+  }
+  return fallback;
+}
+async function readableToBuffer(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFileLike(value) {
+  return isPlainObject(value) && typeof value.arrayBuffer === "function";
+}
+
+// src/client.ts
+class Bitable {
+  client;
+  defaultAppToken;
+  maxRetries;
+  retryDelayMs;
+  defaultConcurrency;
+  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.client = options.sdkClient ?? new lark.Client({
+      appId: options.appId,
+      appSecret: options.appSecret,
+      appType: options.appType ?? lark.AppType.SelfBuild,
+      domain: options.domain ?? lark.Domain.Feishu
+    });
+  }
+  static fromEnv(env = process.env) {
+    return new Bitable({
+      appId: env.FEISHU_APP_ID,
+      appSecret: env.FEISHU_APP_SECRET,
+      defaultAppToken: env.FEISHU_APP_TOKEN
+    });
+  }
+  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
+      }
+    });
+    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 }))
+      }
+    }), "insert records")));
+  }
+  async batchUpdateRecords(payload) {
+    return this.withRetry("batch update records", async () => assertFeishuResponse(await this.client.bitable.v1.appTableRecord.batchUpdate(payload), "batch update records"));
+  }
+  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
+            };
+          })
+        }
+      };
+      if (options.userIdType || options.ignoreConsistencyCheck !== undefined) {
+        payload.params = {
+          user_id_type: options.userIdType,
+          ignore_consistency_check: options.ignoreConsistencyCheck
+        };
+      }
+      return this.batchUpdateRecords(payload);
+    });
+  }
+  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
+      }
+    }), "delete records")));
+  }
+  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
+      });
+    }
+    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
+      }
+    })), "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());
+  }
+  async downLoadFile(fileToken, extra) {
+    return this.downloadFile(fileToken, extra);
+  }
+  resolveConstructorOptions(optionsOrToken, appIdArg, appSecretArg) {
+    const objectMode = typeof optionsOrToken === "object" && optionsOrToken !== null && !Array.isArray(optionsOrToken);
+    const options = objectMode ? optionsOrToken : {
+      defaultAppToken: typeof optionsOrToken === "string" ? optionsOrToken : undefined,
+      appId: appIdArg ?? undefined,
+      appSecret: appSecretArg ?? undefined
+    };
+    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 the constructor or provide FEISHU_APP_ID and FEISHU_APP_SECRET.");
+    }
+    return {
+      ...options,
+      appId,
+      appSecret,
+      defaultAppToken: options.defaultAppToken ?? process.env.FEISHU_APP_TOKEN
+    };
+  }
+  resolveAppToken(overrideToken) {
+    const token = overrideToken ?? this.defaultAppToken;
+    if (!token) {
+      throw new FeishuBitableError("appToken is required. Pass it to the constructor, method options, or FEISHU_APP_TOKEN.");
+    }
+    return token;
+  }
+  async withRetry(label, task) {
+    let lastError;
+    for (let attempt = 1;attempt <= this.maxRetries; attempt++) {
+      try {
+        return await task();
+      } catch (error) {
+        lastError = error;
+        if (attempt === this.maxRetries) {
+          break;
+        }
+        await sleep(this.retryDelayMs * attempt);
+      }
+    }
+    throw new FeishuBitableError(`${label} failed after ${this.maxRetries} attempts`, {
+      cause: lastError
+    });
+  }
+}
+
+// src/index.ts
+import { AppType as AppType2, Domain as Domain2, LoggerLevel } from "@larksuiteoapi/node-sdk";
+var src_default = Bitable;
+export {
+  src_default as default,
+  LoggerLevel,
+  FeishuBitableError,
+  Domain2 as Domain,
+  Bitable,
+  AppType2 as AppType
+};

package/lib/types.d.ts

@@ -0,0 +1,106 @@
+import type * as lark from "@larksuiteoapi/node-sdk";
+export type BitableTextValue = {
+    text?: string;
+    link?: string;
+};
+export type BitableLocationValue = {
+    location?: string;
+    pname?: string;
+    cityname?: string;
+    adname?: string;
+    address?: string;
+    name?: string;
+    full_address?: string;
+};
+export type BitableMemberValue = {
+    id?: string;
+    name?: string;
+    en_name?: string;
+    email?: string;
+    avatar_url?: string;
+};
+export type BitableAttachmentValue = {
+    file_token?: string;
+    name?: string;
+    type?: string;
+    size?: number;
+    url?: string;
+    tmp_url?: string;
+};
+export type BitableFieldValue = string | number | boolean | BitableTextValue | BitableLocationValue | Array<{
+    id?: string;
+    name?: string;
+    avatar_url?: string;
+}> | Array<string> | Array<BitableMemberValue> | Array<BitableAttachmentValue> | {
+    type?: number;
+    value?: unknown;
+};
+export type BitableRecordFields = Record<string, BitableFieldValue>;
+export type BitableRecord = Record<string, unknown> & {
+    record_id: string;
+};
+export type BitableInsertRecord = BitableRecordFields;
+export type BitableUpdateRecord = BitableRecordFields & {
+    record_id: string;
+};
+export type BitableSort = {
+    field_name?: string;
+    desc?: boolean;
+};
+export type BitableFilterCondition = {
+    field_name: string;
+    operator: "is" | "isNot" | "contains" | "doesNotContain" | "isEmpty" | "isNotEmpty" | "isGreater" | "isGreaterEqual" | "isLess" | "isLessEqual" | "like" | "in";
+    value?: string[];
+};
+export type BitableFilterGroup = {
+    conjunction: "and" | "or";
+    conditions?: BitableFilterCondition[];
+    children?: Array<{
+        conjunction: "and" | "or";
+        conditions?: BitableFilterCondition[];
+    }>;
+};
+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 BunFileLike = {
+    arrayBuffer(): Promise<ArrayBuffer>;
+    name?: string;
+};
+export interface BitableConstructorOptions {
+    appId?: string;
+    appSecret?: string;
+    defaultAppToken?: string;
+    appType?: lark.AppType;
+    domain?: lark.Domain | string;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    defaultConcurrency?: number;
+    sdkClient?: lark.Client;
+}
+export interface FetchAllRecordsOptions {
+    viewId?: string;
+    fieldNames?: string[];
+    filter?: BitableFilterGroup;
+    sort?: BitableSort[];
+    pageSize?: number;
+    normalizeFields?: boolean;
+    automaticFields?: boolean;
+}
+export interface BatchOperationOptions {
+    appToken?: string;
+    concurrency?: number;
+    chunkSize?: number;
+}
+export interface UpdateRecordsOptions extends BatchOperationOptions {
+    userIdType?: "user_id" | "union_id" | "open_id";
+    ignoreConsistencyCheck?: boolean;
+}
+export interface UploadFileOptions {
+    file: UploadableFile;
+    fileName?: string;
+    parentType: MediaParentType;
+    parentNode: string;
+    extra?: string;
+}
+export type BitableBatchUpdatePayload = NonNullable<Parameters<lark.Client["bitable"]["v1"]["appTableRecord"]["batchUpdate"]>[0]>;
+export type BitableBatchUpdateResponse = Awaited<ReturnType<lark.Client["bitable"]["v1"]["appTableRecord"]["batchUpdate"]>>;

package/lib/utils.d.ts

@@ -0,0 +1,24 @@
+import { Readable } from "node:stream";
+import type { BitableRecord, BitableRecordFields, UploadableFile } from "./types";
+export declare const FEISHU_BATCH_LIMIT = 500;
+export declare const FEISHU_SIMPLE_UPLOAD_LIMIT: number;
+export declare function chunkArray<T>(items: T[], chunkSize: number): T[][];
+export declare function sleep(ms: number): Promise<void>;
+export declare function runWithConcurrency<T, R>(items: T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function assertFeishuResponse<T extends {
+    code?: number;
+    msg?: string;
+    data?: unknown;
+}>(response: T | null | undefined, action: string): T;
+export declare function normalizeFieldValue(value: unknown): unknown;
+export declare function normalizeRecord(recordId: string | undefined, fields: BitableRecordFields, normalizeFields?: boolean): BitableRecord;
+export declare function normalizeRecordFields(fields: BitableRecordFields): Record<string, unknown>;
+export declare function splitUpdateRecord<T extends Record<string, unknown>>(record: T & {
+    record_id: string;
+}): {
+    recordId: string;
+    fields: Record<string, unknown>;
+};
+export declare function toBuffer(file: UploadableFile): Promise<Buffer>;
+export declare function inferFileName(file: UploadableFile, fallback?: string): string;
+export declare function readableToBuffer(stream: Readable): Promise<Buffer>;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@yuuko1410/feishu-bitable",
+  "version": "0.0.2",
+  "description": "基于 Bun + TypeScript + 飞书官方 SDK 的多维表格操作库",
+  "type": "module",
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir lib --target node --format esm --external @larksuiteoapi/node-sdk && bun build src/index.ts --outfile lib/index.cjs --target node --format cjs --external @larksuiteoapi/node-sdk && tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "feishu",
+    "lark",
+    "bitable",
+    "multidimensional-table",
+    "飞书",
+    "多维表格",
+    "sdk",
+    "api",
+    "batch",
+    "upload",
+    "file"
+  ],
+  "author": "yuuko1410",
+  "license": "MIT",
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.35.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "bun-types": "^1.3.11",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "lib",
+    "README.md"
+  ]
+}