diff --git a/deltachat-jsonrpc/README.md b/deltachat-jsonrpc/README.md index bbbd40c0f..80ed414e8 100644 --- a/deltachat-jsonrpc/README.md +++ b/deltachat-jsonrpc/README.md @@ -4,8 +4,8 @@ This crate provides a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) inte The JSON-RPC API is exposed in two fashions: -* A executable that exposes the JSON-RPC API through a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) server running on localhost. -* The JSON-RPC API can also be called through the [C FFI](../deltachat-ffi). The C FFI needs to be built with the `jsonrpc` feature. It will then expose the functions `dc_jsonrpc_init`, `dc_jsonrpc_request`, `dc_jsonrpc_next_response` and `dc_jsonrpc_unref`. See the docs in the [header file](../deltachat-ffi/deltachat.h) for details. +- A executable that exposes the JSON-RPC API through a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) server running on localhost. +- The JSON-RPC API can also be called through the [C FFI](../deltachat-ffi). The C FFI needs to be built with the `jsonrpc` feature. It will then expose the functions `dc_jsonrpc_init`, `dc_jsonrpc_request`, `dc_jsonrpc_next_response` and `dc_jsonrpc_unref`. See the docs in the [header file](../deltachat-ffi/deltachat.h) for details. We also include a JavaScript and TypeScript client for the JSON-RPC API. The source for this is in the [`typescript`](typescript) folder. The client can easily be used with the WebSocket server to build DeltaChat apps for web browsers or Node.js. See the [examples](typescript/example) for details. @@ -24,16 +24,17 @@ If you want to use the server in a production setup, first build it in release m ```sh cargo build --features webserver --release ``` + You will then find the `deltachat-jsonrpc-server` executable in your `target/release` folder. The executable currently does not support any command-line arguments. By default, once started it will accept WebSocket connections on `ws://localhost:20808/ws`. It will store the persistent configuration and databases in a `./accounts` folder relative to the directory from where it is started. The server can be configured with environment variables: -|variable|default|description| -|-|-|-| -|`DC_PORT`|`20808`|port to listen on| -|`DC_ACCOUNTS_PATH`|`./accounts`|path to storage directory| +| variable | default | description | +| ------------------ | ------------ | ------------------------- | +| `DC_PORT` | `20808` | port to listen on | +| `DC_ACCOUNTS_PATH` | `./accounts` | path to storage directory | If you are targeting other architectures (like KaiOS or Android), the webserver binary can be cross-compiled easily with [rust-cross](https://github.com/cross-rs/cross): @@ -43,32 +44,35 @@ cross build --features=webserver --target armv7-linux-androideabi --release #### Using the TypeScript/JavaScript client -The package includes a JavaScript/TypeScript client which is partially auto-generated through the JSON-RPC library used by this crate ([yerpc](https://github.com/Frando/yerpc/)). Find the source in the [`typescript`](typescript) folder. +The package includes a JavaScript/TypeScript client which is partially auto-generated through the JSON-RPC library used by this crate ([yerpc](https://github.com/Frando/yerpc/)). Find the source in the [`typescript`](typescript) folder. To use it locally, first install the dependencies and compile the TypeScript code to JavaScript: + ```sh cd typescript npm install npm run build ``` -The package is also published on npm under the name [`@deltachat/jsonrpc-client`](https://www.npmjs.com/package/@deltachat/jsonrpc-client). +The package is also published on npm under the name [`@deltachat/jsonrpc-client`](https://www.npmjs.com/package/@deltachat/jsonrpc-client). ###### Usage Stdio server (recommended): + ```typescript import { startDeltaChat } from "@deltachat/stdio-rpc-server"; import { C } from "@deltachat/jsonrpc-client"; const dc = await startDeltaChat("deltachat-data"); console.log(await dc.rpc.getSystemInfo()); -const accounts = await dc.rpc.getAllAccounts() -console.log('accounts', accounts) -dc.close() +const accounts = await dc.rpc.getAllAccounts(); +console.log("accounts", accounts); +dc.close(); ``` Websocket: + ```typescript import { WebsocketDeltaChat as DeltaChat } from '@deltachat/jsonrpc-client''= @@ -81,10 +85,12 @@ console.log('accounts', accounts) ##### Generate TypeScript/JavaScript documentation A script is included to build autogenerated documentation, which includes all RPC methods: + ```sh cd typescript npm run docs ``` + Then open the [`typescript/docs`](typescript/docs) folder in a web browser. ## Development @@ -99,6 +105,7 @@ npm run build npm run example:build npm run example:start ``` + Then, open [`http://localhost:8080/example.html`](http://localhost:8080/example.html) in a web browser. Run `npm run example:dev` to live-rebuild the example app when files changes. diff --git a/deltachat-rpc-server/npm-package/README.md b/deltachat-rpc-server/npm-package/README.md index 4ce994353..f92adadc8 100644 --- a/deltachat-rpc-server/npm-package/README.md +++ b/deltachat-rpc-server/npm-package/README.md @@ -18,11 +18,11 @@ import { startDeltaChat } from "@deltachat/stdio-rpc-server"; import { C } from "@deltachat/jsonrpc-client"; async function main() { - const dc = await startDeltaChat("deltachat-data"); - console.log(await dc.rpc.getSystemInfo()); - dc.close() + const dc = await startDeltaChat("deltachat-data"); + console.log(await dc.rpc.getSystemInfo()); + dc.close(); } -main() +main(); ``` For a more complete example refer to https://github.com/deltachat-bot/echo/tree/master/nodejs_stdio_jsonrpc. @@ -46,7 +46,7 @@ references: When you import this package it searches for the rpc server in the following locations and order: 1. `DELTA_CHAT_RPC_SERVER` environment variable -2. use the PATH when `{takeVersionFromPATH: true}` is supplied in the options. +2. use the PATH when `{takeVersionFromPATH: true}` is supplied in the options. 3. prebuilds in npm packages so by default it uses the prebuilds.