@siyuan-community/siyuan-sdk
v0.3.14
Published
A simple and easy to use SDK for SiYuan.
Downloads
45
Readme
简体中文 | English
A simple and easy to use SDK for SiYuan Note.
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
};