SiYuan Kernel ESM Client (siyuan-kernel-client-esm)

This package provides a single-file, ESM (ECMAScript Module) format API client for interacting with the SiYuan Note Kernel. It offers a KernelApiClient class that integrates all available API methods for direct use in modern JavaScript and TypeScript projects.

This client is generated based on API definitions and is part of the my-siyuan-kernel-SDK project.

Features

• Single File: Easy to import and integrate.
• ESM Format: Uses standard import/export syntax.
• Comprehensive: Includes methods for (almost) all SiYuan Kernel APIs.
• JSDoc Annotations: Methods and their parameters/return types are documented with JSDoc, providing good editor autocompletion and type hinting in JavaScript.
• Lightweight: The client itself has no runtime dependencies.

Installation

npm install siyuan-kernel-client-esm
# or
yarn add siyuan-kernel-client-esm
# or
pnpm add siyuan-kernel-client-esm

Usage

import KernelApiClient from 'siyuan-kernel-client-esm';
// or if your environment supports it and package.json type is "module":
// import KernelApiClient from './node_modules/siyuan-kernel-client-esm/kernelApiClient.js';


// Initialize the client
const client = new KernelApiClient({
  baseUrl: 'http://127.0.0.1:6806', // Your SiYuan Kernel address
  apiToken: 'YOUR_API_TOKEN_IF_NEEDED', // Provide if API requires authentication
});

// Example: Get Kernel Version
async function fetchKernelVersion() {
  try {
    const version = await client.version(); // Method name might vary based on API definition
    console.log('SiYuan Kernel Version:', version);
  } catch (error) {
    console.error('Failed to fetch version:', error.message);
    if (error.data) {
      console.error('Error details:', error.data);
    }
  }
}

fetchKernelVersion();

// Example: Call an API that requires parameters
async function getDocumentInfo(docId) {
  try {
    // Assuming an API 'getDoc' exists and takes an 'id' parameter
    // The actual method name and parameter structure depend on the API definitions
    // used during client generation.
    const docData = await client.getDoc({ id: docId, anotherParam: 'value' });
    console.log('Document Data:', docData);
  } catch (error) {
    console.error(`Failed to fetch document ${docId}:`, error.message);
  }
}

// getDocumentInfo('your-document-id');

API Client Generation

This client (kernelApiClient.js) is automatically generated by the generateSingleFileClient.cjs script, which is part of the main my-siyuan-kernel-SDK repository. The script reads API definitions (typically from an apiDefs directory, which should use Zod for schema definitions) and outputs this single-file client.

If you have this package as part of a monorepo setup (e.g., with my-siyuan-kernel-SDK), you can typically regenerate the kernelApiClient.js by running the build script defined in this package's package.json (e.g., npm run build or pnpm build within this package's directory). This build script would invoke node generateSingleFileClient.cjs.

Configuration

When instantiating KernelApiClient, you can pass a configuration object:

• baseUrl (string, optional): The base URL of the SiYuan Kernel. Defaults to http://127.0.0.1:6806.
• apiToken (string, optional): The API token for authentication. Defaults to an empty string.
• customFetch (function, optional): A custom fetch implementation. Defaults to the globally available fetch.

Known Limitations

The current version of the generated client has the following known limitations:

• FormData Support: The client is primarily designed for APIs that use JSON request/response bodies. It does not have built-in, specialized support for APIs requiring multipart/form-data (e.g., for file uploads). For such APIs, you might need to construct and send the FormData request manually or extend the client's capabilities.
• WebSocket (WS) Support: The underlying fetch API used by this client does not support WebSocket connections. Operations requiring WebSockets cannot be handled by this client.
• Server-Sent Events (SSE) Support: While fetch can initiate requests that return SSE streams, this client does not include built-in logic to parse and handle SSE event streams. If an API returns an SSE stream, you would receive the raw stream and would need to implement the SSE parsing logic yourself.
• Error Handling: The _fetchWrapper provides basic error handling (rejecting on non-ok HTTP statuses and attempting to parse JSON error responses). However, specific error codes or complex error response structures might require additional handling in your application code.

License

This package is licensed under the AGPL-3.0-or-later. See the LICENSE file for full details (Note: A separate LICENSE file is typically included at the root of the main SDK project or within this package upon distribution).

This README is specific to the siyuan-kernel-client-esm package.