@wetoria/siyuan-sdk 0.0.2 → 0.0.3

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from './transaction';
 /**
  * Frequently used data structures in SiYuan
  */
@@ -6,6 +7,7 @@ export type BlockId = string;
 export type NotebookId = string;
 export type PreviousID = BlockId;
 export type ParentID = BlockId | DocumentId;
+export type DataType = "markdown" | "dom";
 export interface Notebook {
     id: NotebookId;
     name: string;
@@ -23,6 +25,41 @@ export interface NotebookConf {
 }
 export type BlockType = "d" | "s" | "h" | "t" | "i" | "p" | "f" | "audio" | "video" | "other";
 export type BlockSubType = "d1" | "d2" | "s1" | "s2" | "s3" | "t1" | "t2" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "table" | "task" | "toggle" | "latex" | "quote" | "html" | "code" | "footnote" | "cite" | "collection" | "bookmark" | "attachment" | "comment" | "mindmap" | "spreadsheet" | "calendar" | "image" | "audio" | "video" | "other";
+/**
+ * 块属性接口 - 可以手动修改的属性
+ * 注释掉的内容也存在，这里用于展示全部字段类型，但禁止手动修改
+ */
+export interface IBlockAttrs {
+    "name"?: string;
+    "alias"?: string;
+    "memo"?: string;
+    "bookmark"?: string;
+    "tags"?: string;
+    "fold"?: "1" | "";
+    "heading-fold"?: "1" | "";
+    "style"?: string;
+    "scroll"?: string;
+    "id"?: string;
+    "title"?: string;
+    "updated"?: string;
+    "type"?: string;
+    "icon"?: string;
+    "status"?: string;
+    "refcount"?: string;
+    "parent-heading"?: string;
+    "embed-content"?: string;
+    "custom-avs"?: string;
+    "custom-avs-names"?: string;
+    "data-av-type"?: string;
+    "custom-riff-decks"?: string;
+    [key: `custom-dailynote-${string}`]: string;
+    [key: `custom-${string}`]: string;
+}
+/**
+ * 允许设置的块属性类型
+ * 排除了系统自动维护的属性：id、updated、type、status、refcount、parent-heading、embed-content、scroll
+ */
+export type ISettableBlockAttrs = Omit<IBlockAttrs, "id" | "updated" | "type" | "status" | "refcount" | "parent-heading" | "embed-content" | "scroll">;
 export interface Block {
     id: BlockId;
     parent_id?: BlockId;
@@ -42,7 +79,7 @@ export interface Block {
     type: BlockType;
     subtype: BlockSubType;
     /**
-     * string of { [key: string]: string }
+     * 块属性（Inline Attributes List）
      * For instance: "{: custom-type=\"query-code\" id=\"20230613234017-zkw3pr0\" updated=\"20230613234509\"}"
      */
     ial?: string;
@@ -50,29 +87,6 @@ export interface Block {
     created: string;
     updated: string;
 }
-export interface doOperation {
-    action: string;
-    data: string;
-    id: BlockId;
-    parentID: BlockId | DocumentId;
-    previousID: BlockId;
-    retData: null;
-}
-declare global {
-    interface Window {
-        siyuan: {
-            notebooks: any;
-            menus: any;
-            dialogs: any;
-            blockPanels: any;
-            storage: any;
-            user: any;
-            ws: any;
-            languages: any;
-            config: import('siyuan').Config.IConf;
-        };
-    }
-}
 export interface IBreadcrumb {
     id: string;
     name: string;
@@ -85,4 +99,20 @@ export interface backlinkData {
     blockPaths: IBreadcrumb[];
     expand: boolean;
 }
+/**
+ * 子块信息（用于 getChildBlocks 返回值）
+ */
+export interface ChildBlock {
+    id: BlockId;
+    type: BlockType;
+    content?: string;
+    markdown?: string;
+}
+/**
+ * 块的 DOM 结构（用于 getBlockDOM 返回值）
+ */
+export interface BlockDOM {
+    dom: string;
+    id: BlockId;
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAC/B,MAAM,MAAM,OAAO,GAAG,MAAM,CAAA;AAC5B,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAC/B,MAAM,MAAM,UAAU,GAAG,OAAO,CAAA;AAChC,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAA;AAE3C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,UAAU,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,iBAAiB,EAAE,MAAM,CAAA;IACzB,qBAAqB,EAAE,MAAM,CAAA;IAC7B,iBAAiB,EAAE,MAAM,CAAA;IACzB,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,MAAM,SAAS,GACjB,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,OAAO,GACP,OAAO,GACP,OAAO,CAAA;AAEX,MAAM,MAAM,YAAY,GACpB,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,OAAO,GACP,MAAM,GACN,QAAQ,GACR,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,UAAU,GACV,MAAM,GACN,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,SAAS,GACT,SAAS,GACT,aAAa,GACb,UAAU,GACV,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,CAAA;AAEX,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,OAAO,CAAA;IACX,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,UAAU,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,YAAY,CAAA;IACrB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,OAAO,CAAA;IACX,QAAQ,EAAE,OAAO,GAAG,UAAU,CAAA;IAC9B,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,IAAI,CAAA;CACd;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,MAAM,EAAE;YACN,SAAS,EAAE,GAAG,CAAA;YACd,KAAK,EAAE,GAAG,CAAA;YACV,OAAO,EAAE,GAAG,CAAA;YACZ,WAAW,EAAE,GAAG,CAAA;YAChB,OAAO,EAAE,GAAG,CAAA;YACZ,IAAI,EAAE,GAAG,CAAA;YACT,EAAE,EAAE,GAAG,CAAA;YACP,SAAS,EAAE,GAAG,CAAA;YACd,MAAM,EAAE,OAAO,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAA;SACtC,CAAA;KACF;CACF;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,GAAG,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,WAAW,EAAE,CAAA;IACzB,MAAM,EAAE,OAAO,CAAA;CAChB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.js

@@ -1,2 +1,2 @@
-export {};
+export * from './transaction';
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA"}

package/dist/types/transaction/index.d.ts

@@ -0,0 +1,39 @@
+import { BlockId, DocumentId } from '../index';
+export declare enum ActionTypes {
+    insert = "insert",
+    update = "update",
+    delete = "delete",
+    move = "move"
+}
+export interface doOperation {
+    action: ActionTypes;
+    data: string;
+    id: BlockId;
+    parentID: BlockId | DocumentId;
+    previousID: BlockId;
+    nextID?: string;
+    retData: null;
+    blockIDs?: string[] | null;
+    blockID?: string;
+    deckID?: string;
+    avID?: string;
+    srcIDs?: string[] | null;
+    srcs?: string[] | null;
+    isDetached?: boolean;
+    ignoreFillFilter?: boolean;
+    name?: string;
+    type?: string;
+    format?: string;
+    keyID?: string;
+    rowID?: string;
+    isTwoWay?: boolean;
+    backRelationKeyID?: string;
+    removeDest?: boolean;
+    layout?: string;
+}
+export interface TransactionItem {
+    timestamp: string;
+    doOperations: doOperation[];
+    undoOperations: doOperation[] | null;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/transaction/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/transaction/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,UAAU,EACX,MAAM,UAAU,CAAA;AAEjB,oBAAY,WAAW;IACrB,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,OAAO,CAAA;IACX,QAAQ,EAAE,OAAO,GAAG,UAAU,CAAA;IAC9B,UAAU,EAAE,OAAO,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,IAAI,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACtB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAGD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,WAAW,EAAE,CAAA;IAC3B,cAAc,EAAE,WAAW,EAAE,GAAG,IAAI,CAAA;CACrC"}

package/dist/types/transaction/index.js

@@ -0,0 +1,8 @@
+export var ActionTypes;
+(function (ActionTypes) {
+    ActionTypes["insert"] = "insert";
+    ActionTypes["update"] = "update";
+    ActionTypes["delete"] = "delete";
+    ActionTypes["move"] = "move";
+})(ActionTypes || (ActionTypes = {}));
+//# sourceMappingURL=index.js.map

package/dist/types/transaction/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/transaction/index.ts"],"names":[],"mappings":"AAKA,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,gCAAiB,CAAA;IACjB,gCAAiB,CAAA;IACjB,gCAAiB,CAAA;IACjB,4BAAa,CAAA;AACf,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wetoria/siyuan-sdk",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "SiYuan SDK",
   "type": "module",
   "main": "./dist/index.js",

package/src/api/attr/index.ts

@@ -1,5 +1,9 @@
 import type { SyApiMethodResponse } from '../../core/index.js'
-import type { BlockId } from '../../types/index.js'
+import type {
+  BlockId,
+  IBlockAttrs,
+  ISettableBlockAttrs,
+} from '../../types/index.js'
 import { SiYuanAPI } from '../../core/index.js'
 
 /**
@@ -9,36 +13,45 @@ export interface AttrAPI {
   /**
    * 设置块属性
    * @path /api/attr/setBlockAttrs
+   * @param id - The ID of the block
+   * @param attrs - The attributes to set. System properties (id, updated, type, status, refcount, parent-heading, embed-content, scroll) are not allowed to be modified
+   * @returns - Promise<{ code: number, msg: string, data: null }>
    */
   setBlockAttrs: (
     id: BlockId,
-    attrs: { [key: string]: string }
-  ) => SyApiMethodResponse<any>
+    attrs: Partial<ISettableBlockAttrs>
+  ) => SyApiMethodResponse<null>
   /**
    * 获取块属性
    * @path /api/attr/getBlockAttrs
+   * @param id - The ID of the block
+   * @returns - Promise<{ code: number, msg: string, data: IBlockAttrs }>
    */
-  getBlockAttrs: (id: BlockId) => SyApiMethodResponse<{
-    [key: string]: string
-  }>
+  getBlockAttrs: (id: BlockId) => SyApiMethodResponse<IBlockAttrs>
   /**
    * 批量设置块属性
    * @path /api/attr/batchSetBlockAttrs
+   * @param blockAttrs - Array of block attributes to set
+   * @param blockAttrs[].id - The ID of the block
+   * @param blockAttrs[].attrs - The attributes to set. System properties (id, updated, type, status, refcount, parent-heading, embed-content, scroll) are not allowed to be modified
+   * @returns - Promise<{ code: number, msg: string, data: null }>
    */
   batchSetBlockAttrs: (blockAttrs: Array<{
     id: BlockId
-    attrs: { [key: string]: string }
-  }>) => SyApiMethodResponse<any>
+    attrs: Partial<ISettableBlockAttrs>
+  }>) => SyApiMethodResponse<null>
   /**
    * 批量获取块属性
    * @path /api/attr/batchGetBlockAttrs
+   * @param ids - The IDs of the blocks
+   * @returns - Promise<{ code: number, msg: string, data: { [key: string]: IBlockAttrs } }>
    */
   batchGetBlockAttrs: (ids: BlockId[]) => SyApiMethodResponse<{
-    [key: string]: string
+    [key: string]: IBlockAttrs
   }>
 }
 
-SiYuanAPI.prototype.setBlockAttrs = function (id: string, attrs: { [key: string]: string }) {
+SiYuanAPI.prototype.setBlockAttrs = function (id: string, attrs: Partial<ISettableBlockAttrs>) {
   return this.request('/api/attr/setBlockAttrs', {
     id,
     attrs,
@@ -49,7 +62,7 @@ SiYuanAPI.prototype.getBlockAttrs = function (id: string) {
   return this.request('/api/attr/getBlockAttrs', { id })
 }
 
-SiYuanAPI.prototype.batchSetBlockAttrs = function (blockAttrs: Array<{ id: string, attrs: { [key: string]: string } }>) {
+SiYuanAPI.prototype.batchSetBlockAttrs = function (blockAttrs: Array<{ id: string, attrs: Partial<ISettableBlockAttrs> }>) {
   return this.request('/api/attr/batchSetBlockAttrs', { blockAttrs })
 }
 

package/src/api/block/index.ts

@@ -1,7 +1,11 @@
 import type { SyApiMethodResponse } from '../../core/index.js'
 import type {
+  Block,
+  BlockDOM,
   BlockId,
+  ChildBlock,
   NotebookId,
+  TransactionItem,
 } from '../../types/index.js'
 import { SiYuanAPI } from '../../core/index.js'
 
@@ -12,40 +16,59 @@ export interface BlockAPI {
   /**
    * 插入块
    * @path /api/block/insertBlock
+   * @param data - The data for the block
+   * @param data.dataType - The type of the data(markdown, dom), default is 'markdown'
+   * @param data.data - The data for the block
+   * @param data.nextID - The next ID of the block
+   * @param data.previousID - The previous ID of the block
+   * @param data.parentID - The parent ID of the block
+   * @returns - Promise<{ code: number, msg: string, data: TransactionItem[] }>
    */
-  insertBlock: (
-    dataType: 'markdown' | 'dom',
-    data: string,
-    nextID?: BlockId,
-    previousID?: BlockId,
+  insertBlock: (data: {
+    dataType?: 'markdown' | 'dom'
+    data: string
+    nextID?: BlockId
+    previousID?: BlockId
     parentID?: BlockId
-  ) => SyApiMethodResponse<any[]>
+  }) => SyApiMethodResponse<TransactionItem[]>
   /**
    * 在块的开头插入内容
    * @path /api/block/prependBlock
+   * @param dataType - The type of the data(markdown, dom)
+   * @param data - The data for the block
+   * @param parentID - The parent ID of the block
+   * @returns - Promise<{ code: number, msg: string, data: TransactionItem[] }>
    */
   prependBlock: (
     dataType: 'markdown' | 'dom',
     data: string,
     parentID: BlockId
-  ) => SyApiMethodResponse<any[]>
+  ) => SyApiMethodResponse<TransactionItem[]>
   /**
    * 在块的末尾追加内容
    * @path /api/block/appendBlock
+   * @param dataType - The type of the data(markdown, dom), default is 'markdown'
+   * @param data - The data for the block
+   * @param parentID - The parent ID of the block
+   * @returns - Promise<{ code: number, msg: string, data: TransactionItem[] }>
    */
   appendBlock: (
     dataType: 'markdown' | 'dom',
     data: string,
     parentID: BlockId
-  ) => SyApiMethodResponse<any[]>
+  ) => SyApiMethodResponse<TransactionItem[]>
   /**
    * 追加 Markdown 内容到块（便捷方法）
    * @path wrapper: uses appendBlock
+   * @param params - The parameters for appending markdown content
+   * @param params.data - The markdown data for the block
+   * @param params.parentID - The parent ID of the block
+   * @returns - Promise<{ code: number, msg: string, data: TransactionItem[] }>
    */
   appendMDToBlock: (params: {
     data: string
     parentID: BlockId
-  }) => SyApiMethodResponse<any[]>
+  }) => SyApiMethodResponse<TransactionItem[]>
   /**
    * 追加 Markdown 内容到块并返回块 ID（便捷方法）
    * @path wrapper: uses appendBlock
@@ -66,17 +89,23 @@ export interface BlockAPI {
   /**
    * 更新块内容
    * @path /api/block/updateBlock
+   * @param dataType - The type of the data(markdown, dom)
+   * @param data - The data for the block
+   * @param id - The ID of the block to update
+   * @returns - Promise<{ code: number, msg: string, data: TransactionItem[] }>
    */
   updateBlock: (
     dataType: 'markdown' | 'dom',
     data: string,
     id: BlockId
-  ) => SyApiMethodResponse<any[]>
+  ) => SyApiMethodResponse<TransactionItem[]>
   /**
    * 删除块
    * @path /api/block/deleteBlock
+   * @param id - The ID of the block to delete
+   * @returns - Promise<{ code: number, msg: string, data: TransactionItem[] }>
    */
-  deleteBlock: (id: BlockId) => SyApiMethodResponse<any[]>
+  deleteBlock: (id: BlockId) => SyApiMethodResponse<TransactionItem[]>
   /**
    * 移动块
    * @path /api/block/moveBlock
@@ -94,8 +123,10 @@ export interface BlockAPI {
   /**
    * 获取子块列表
    * @path /api/block/getChildBlocks
+   * @param id - The ID of the parent block
+   * @returns - Promise<{ code: number, msg: string, data: ChildBlock[] }>
    */
-  getChildBlocks: (id: BlockId) => SyApiMethodResponse<any[]>
+  getChildBlocks: (id: BlockId) => SyApiMethodResponse<ChildBlock[]>
   /**
    * 获取块的索引位置
    * @path /api/block/getBlocksIndexes
@@ -116,21 +147,34 @@ export interface BlockAPI {
    * 获取块信息（通过 SQL 查询）
    * @path wrapper: uses sql
    */
-  getBlockInfo: (id: BlockId) => SyApiMethodResponse<any>
+  getBlockInfo: (id: BlockId) => SyApiMethodResponse<Block>
   /**
    * 获取块的 DOM 结构
    * @path /api/block/getBlockDOM
+   * @param id - The ID of the block
+   * @returns - Promise<{ code: number, msg: string, data: BlockDOM }>
    */
-  getBlockDOM: (id: BlockId) => SyApiMethodResponse<any>
+  getBlockDOM: (id: BlockId) => SyApiMethodResponse<BlockDOM>
+  /**
+   * 批量获取块的 DOM 结构
+   * @path /api/block/getBlockDOMs
+   * @param ids - The IDs of the blocks
+   * @returns - Promise<{ code: number, msg: string, data: BlockDOM[] }>
+   */
+  getBlockDOMs: (ids: BlockId[]) => SyApiMethodResponse<BlockDOM[]>
 }
 
-SiYuanAPI.prototype.insertBlock = function (dataType: 'markdown' | 'dom', data: string, nextID?: string, previousID?: string, parentID?: string) {
+
+SiYuanAPI.prototype.insertBlock = function (data: {
+  dataType?: 'markdown' | 'dom'
+  data: string
+  nextID?: string
+  previousID?: string
+  parentID?: string
+}) {
   return this.request('/api/block/insertBlock', {
-    dataType,
-    data,
-    nextID,
-    previousID,
-    parentID,
+    ...data,
+    dataType: data.dataType || 'markdown',
   })
 }
 
@@ -224,3 +268,7 @@ SiYuanAPI.prototype.getBlockDOM = function (id: string) {
   return this.request('/api/block/getBlockDOM', { id })
 }
 
+SiYuanAPI.prototype.getBlockDOMs = function (ids: string[]) {
+  return this.request('/api/block/getBlockDOMs', { ids })
+}
+

package/src/api/file/index.ts

@@ -1,6 +1,7 @@
 import {
   SiYuanAPI,
   SyApiMethodResponse,
+  SyApiResponse,
 } from '../../core/index.js'
 
 /**
@@ -10,8 +11,17 @@ export interface FileAPI {
   /**
    * 获取文件内容
    * @path /api/file/getFile
+   * @param path - The file path
+   * @returns - Promise<string | SyApiResponse<string | null>>
+   *   返回值可能是：
+   *   - 文件存在时：直接返回文件内容（字符串）
+   *   - 文件不存在或出错时：标准结构 { code: number, msg: string, data: null }
+   *     - code: 404 表示文件不存在
+   *     - code: 403 表示路径无效或权限不足
+   *     - code: 405 表示路径是目录
+   *     - code: 500 表示读取文件失败
    */
-  getFile: (path: string) => SyApiMethodResponse<any>
+  getFile: (path: string) => Promise<string | SyApiResponse<string | null>>
   /**
    * 上传/创建文件
    * @path /api/file/putFile

package/src/api/notebook/index.ts

@@ -1,16 +1,25 @@
 import type { SyApiMethodResponse } from '../../core/index.js'
-import type { NotebookId } from '../../types/index.js'
+import type {
+  Notebook,
+  NotebookId,
+} from '../../types/index.js'
 import { SiYuanAPI } from '../../core/index.js'
 
+
+export interface RespLsNotebooks {
+  notebooks: Notebook[]
+}
+
 /**
  * Notebook API 类型定义
  */
 export interface NotebookAPI {
   /**
-   * 列出所有笔记本
+   * List all notebooks
    * @path /api/notebook/lsNotebooks
+   * @returns - Promise<{ notebooks: Notebook[] }>
    */
-  lsNotebooks: () => SyApiMethodResponse<any>
+  lsNotebooks: () => SyApiMethodResponse<RespLsNotebooks>
   /**
    * 打开笔记本
    * @path /api/notebook/openNotebook

package/src/core/index.ts

@@ -20,24 +20,34 @@ export interface SyApiResponse<T = any> {
   data: T
 }
 
-export type SyApiMethodResponse<T = any> = Promise<SyApiResponse<T> | IWebSocketData>
+export type SyApiMethodResponse<T = any> = Promise<SyApiResponse<T> | IWebSocketData | T>
 
 
 /**
  * 请求选项
  */
 export interface RequestOptions {
-  /** 请求方法 */
+  /**
+   * 请求方法
+   * @default POST
+   * @description 请求方法
+   * @example 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+   */
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
-  /** 请求头 */
+  /**
+   * 请求头
+   * @default {}
+   * @description 请求头
+   * @example { 'Content-Type': 'application/json' }
+   */
   headers?: Record<string, string>
-  /** 超时时间（毫秒） */
+  /**
+   * 超时时间（毫秒）
+   * @default 30000
+   */
   timeout?: number
 }
 
-
-
-
 /**
  * 基础 Fetch 函数类型（统一的结构）
  */
@@ -76,6 +86,46 @@ export class SiYuanAPI {
 
   constructor(config: SiYuanAPIConfig) {
     this.setConfig(config)
+    // 自动绑定所有原型方法，确保在解构或箭头函数中调用时 this 不会丢失
+    this._bindMethods()
+  }
+
+  /**
+   * 绑定所有原型方法到当前实例
+   * 这样即使方法被解构，this 也能正确指向实例
+   * @private
+   */
+  private _bindMethods(): void {
+    const prototype = SiYuanAPI.prototype
+    const boundMethods = new Set<string>()
+
+    // 获取原型上的所有属性名（包括不可枚举的）
+    const propertyNames = Object.getOwnPropertyNames(prototype)
+
+    for (const name of propertyNames) {
+      // 跳过已绑定的方法和特殊方法
+      if (
+        boundMethods.has(name)
+        || name === 'constructor'
+        || name.startsWith('_')
+        || name === 'setConfig'
+        || name === 'getConfig'
+        || name === 'extractData'
+        || name === '_bindMethods'
+        || name === 'request'
+        || name === 'post'
+      ) {
+        continue
+      }
+
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, name)
+
+      // 只绑定函数类型的属性
+      if (descriptor && typeof descriptor.value === 'function') {
+        ;(this as any)[name] = descriptor.value.bind(this)
+        boundMethods.add(name)
+      }
+    }
   }
 
   setConfig(config: SiYuanAPIConfig): void {

package/src/index.ts

@@ -1,7 +1,14 @@
 /**
  * SiYuan SDK
+ *
+ * Copyright (c) 2023 Wetoria. All rights reserved.
+ * https://github.com/wetoria/sy-plugin-enhance
+ *
+ * See API Document in [API.md](https://github.com/siyuan-note/siyuan/blob/master/API.md)
+ * API 文档见 [API_zh_CN.md](https://github.com/siyuan-note/siyuan/blob/master/API_zh_CN.md)
  */
 
+
 export * from './api/index.js'
 export type * from './core/index.js'
 export * from './core/index.js'