@siyuan-community/siyuan-sdk

SiYuan SDK

---

简体中文 | English

---

A simple and easy to use SDK for SiYuan Note.

• Getting Started
  • Installation
• Examples
  • Initialize the client
  • Update client 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

import { Client } from "siyuan-sdk";

/* Initialize the client */
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) HTTP request timeout
     * Unit: milliseconds (ms)
     * @default: 60_000
     */
    timeout: 10_000,

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

Update client configuration

client.updateOptions({
    timeout: 30_000, // Change HTTP request timeout to 30 seconds
});

Call Kernel API (async)

import { KernelError, HTTPError } from "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 { KernelError, HTTPError } from "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/src/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.1.1 / 2023-07-18

• v0.1.0 ... v0.1.1
• 添加 API /api/filetree/getHPathByID | Add API /api/filetree/getHPathByID
• schema ID 更改为 https://github.com/:user/:repo/raw/:branch/* | Change schema ID to https://github.com/:user/:repo/raw/:branch/*
• 更新 API /api/filetree/getHPathByID | Update API /api/filetree/getHPathByID
• 添加 API /api/filetree/getDoc | Add API /api/filetree/getDoc
• 添加 API /api/block/getBlockDOM | Add API /api/block/getBlockDOM
• 添加 API /api/block/getBlockBreadcrumb | Add API /api/block/getBlockBreadcrumb
• 添加 API /api/block/getBlockInfo | Add API /api/block/getBlockInfo