@siyuan-community/siyuan-sdk

SiYuan SDK

---

简体中文 | English

---

A simple and easy to use SDK for SiYuan Note.

• Getting Started
  • Installation
• Examples
  • Initialize the client
    • Default configuration
    • Configure as a XHR client
    • Configure as a Fetch client
  • Update the model of HTTP client
  • Update client global configuration
  • Call Kernel API (async)
  • Call Kernel API (Promise)
  • Use type definitions
• References
  • API References
• Changelog

Getting Started

Installation

Using npm:

$ npm install @siyuan-community/siyuan-sdk

Using pnpm:

$ pnpm i @siyuan-community/siyuan-sdk

Using yarn:

$ yarn add @siyuan-community/siyuan-sdk

Examples

Initialize the client

Default configuration

import { Client } from "@siyuan-community/siyuan-sdk";

/* Initialize the client (Axios is used to issue XHR by default) */
const client = new Client({
    /**
     * (Optional) SiYuan kernel service URL
     * @default: document.baseURI
     */
    baseURL: "http://localhost:6806/",

    /**
     * (Optional) SiYuan kernel service token
     * @default: empty
     */
    token: "0123456789abcdef", // , default is empty

    /**
     * (Optional) Other Axios request configurations
     * REF: https://axios-http.com/zh/docs/req_config
     * REF: https://www.axios-http.cn/docs/req_config
     */
});

Configure as a XHR client

import { Client } from "@siyuan-community/siyuan-sdk";

/* Initialize the XHR client (Axios is used to issue XHR) */
const client = new Client(
    {
        /**
         * (Optional) SiYuan kernel service URL
         * @default: document.baseURI
         */
        baseURL: "http://localhost:6806/",

        /**
         * (Optional) SiYuan kernel service token
         * @default: empty
         */
        token: "0123456789abcdef", // , default is empty

        /**
         * (Optional) Other Axios request configurations
         * REF: https://axios-http.com/zh/docs/req_config
         * REF: https://www.axios-http.cn/docs/req_config
         */
    },
    "xhr",
);

Configure as a Fetch client

import { Client } from "@siyuan-community/siyuan-sdk";

/* Initialize the Fetch client (ofetch is used to issue Fetch request) */
const client = new Client(
    {
        /**
         * (Optional) SiYuan kernel service URL
         * @default: document.baseURI
         */
        baseURL: "http://localhost:6806/",

        /**
         * (Optional) SiYuan kernel service token
         * @default: empty
         */
        token: "0123456789abcdef", // , default is empty

        /**
         * (Optional) Other ofetch request configurations
         * REF: https://www.npmjs.com/package/ofetch
         * REF: https://www.jsdocs.io/package/ofetch
         */
    },
    "fetch",
);

Update the model of HTTP client

client._setClientType("fetch"); // Change the client mode to Fetch
client._setClientType("xhr"); // Change the client mode to XHR

Update client global configuration

/* The global configuration of the current mode is updated by default */
client._updateOptions({
    token: "abcdef0123456789", // Change SiYuan API token to abcdef0123456789
});

/* Update the global configuration of XHR client Axios */
client._updateOptions(
    {
        timeout: 10_000, // The request timeout period is 10s
        /* Other Axios request configurations */
    },
    "xhr",
);

/* Update the global configuration of Fetch client ofetch */
client._updateOptions(
    {
        retry: 3, // The number of request retries is 3
        /* Other ofetch request configurations */
    },
    "fetch",
);

Call Kernel API (async)

import { HTTPError, KernelError } from "@siyuan-community/siyuan-sdk";

async function func() {
    try {
        /**
         * Asynchronously call the Kernel API `/api/notification/pushMsg`
         * Push notification message
         */
        const response = await client.pushMsg({
            msg: "This is a notification message", // Notification content
            timeout: 7_000, // Notification display time
        });
        console.log(response); // { "code": 0, "msg": "", "data": { "id": "0a1b2c3" } }
    }
    catch (error) {
        if (error instanceof KernelError) { // Kernel error
            console.error(error.body); // Response body { "code": -1, "msg": "error message", "data": null }
        }
        else if (error instanceof HTTPError) { // HTTP request error
            console.error(error.status); // HTTP status code
        }
        else { // Other uncaught errors
            throw error;
        }
    }
    finally {
        /* ... */
    }
}

Call Kernel API (Promise)

import { HTTPError, KernelError } from "@siyuan-community/siyuan-sdk";

function func() {
    /**
     * Asynchronously call the Kernel API `/api/notification/pushErrMsg`
     * Push error message
     */
    client
        .pushErrMsg({
            msg: "This is an error message", // Notification content
            timeout: 7_000, // Notification display time
        })
        .then((response) => {
            console.log(response); // { "code": 0, "msg": "", "data": { "id": "0a1b2c3" } }
        })
        .catch((error) => {
            if (error instanceof KernelError) { // Kernel error
                console.error(error.body); // Response body { "code": -1, "msg": "error message", "data": null }
            }
            else if (error instanceof HTTPError) { // HTTP request error
                console.error(error.status); // HTTP status code
            }
            else { // Other uncaught errors
                throw error;
            }
        })
        .finally(() => {
            /* ... */
        });
}

Use type definitions

import { types } from "@siyuan-community/siyuan-sdk";

const payload: types.kernel.api.notification.pushMsg.IPayload = {
    msg: "This is a notification message", // Notification content
    timeout: 7_000, // Notification display time
};

import pushMsg from "@siyuan-community/siyuan-sdk/dist/types/kernel/api/notification/pushMsg";

const payload: pushMsg.IPayload = {
    msg: "This is a notification message", // Notification content
    timeout: 7_000, // Notification display time
};

References

API References

• SiYuan API Documentation
• JSON Schema Definitions

Changelog

CHANGELOG.md

Changelog

v0.3.14 / 2024-11-20

• v0.3.13 ... v0.3.14
• 修复类型定义文件入口路径错误问题 | Fix the issue of incorrect entry path of type definition file
• 调整 API /api/system/getConf | Adjust API /api/system/getConf
• 调整 API /api/repo/openRepoSnapshotDoc | Adjust API /api/repo/openRepoSnapshotDoc
• 调整 API /api/block/getBlockBreadcrumb 测试用例 | Adjust API /api/block/getBlockBreadcrumb test case
• 调整 API /api/search/fullTextSearchBlock | Adjust API /api/search/fullTextSearchBlock
• 调整 API /api/system/getConf | Adjust API /api/system/getConf