From 5f7ca4ff9afcd02feff74601a5412bcd4a07b211 Mon Sep 17 00:00:00 2001 From: Septias Date: Sat, 2 Nov 2024 09:53:02 +0100 Subject: [PATCH 1/9] add alias handling --- src/chat.rs | 23 +++++++++++++++++++++++ src/mimeparser.rs | 9 +++++++++ src/receive_imf.rs | 8 ++++++++ src/stock_str.rs | 2 +- 4 files changed, 41 insertions(+), 1 deletion(-) diff --git a/src/chat.rs b/src/chat.rs index 9d36f30d8d..30c432aaa9 100644 --- a/src/chat.rs +++ b/src/chat.rs @@ -3481,6 +3481,29 @@ pub async fn get_chat_contacts(context: &Context, chat_id: ChatId) -> Result Result> { + // Normal chats do not include SELF. Group chats do (as it may happen that one is deleted from a + // groupchat but the chats stays visible, moreover, this makes displaying lists easier) + + let list = context + .sql + .query_map( + "SELECT cc.contact_id + FROM chats_contacts cc + LEFT JOIN contacts c + ON c.id=cc.contact_id + WHERE cc.chat_id=? AND c.id!=1 + ORDER BY c.id=1, c.last_seen DESC, c.id DESC;", + (chat_id,), + |row| row.get::<_, ContactId>(0), + |ids| ids.collect::, _>>().map_err(Into::into), + ) + .await?; + + Ok(list) +} + /// Creates a group chat with a given `name`. pub async fn create_group_chat( context: &Context, diff --git a/src/mimeparser.rs b/src/mimeparser.rs index 93ac536516..662b8c7f4e 100644 --- a/src/mimeparser.rs +++ b/src/mimeparser.rs @@ -770,6 +770,15 @@ impl MimeMessage { Ok(()) } + /// Set different sender name for a message. + /// This overrides the name set by the `set_config()`-option `displayname`. + pub fn set_override_sender_name(&mut self, name: Option) { + self.parts.iter_mut().for_each(|part| { + part.param + .set_optional(Param::OverrideSenderDisplayname, name.clone()); + }); + } + async fn avatar_action_from_header( &mut self, context: &Context, diff --git a/src/receive_imf.rs b/src/receive_imf.rs index f3d513a603..1a6ee01358 100644 --- a/src/receive_imf.rs +++ b/src/receive_imf.rs @@ -1807,6 +1807,14 @@ async fn lookup_chat_by_reply( // If this was a private message just to self, it was probably a private reply. // It should not go into the group then, but into the private chat. if is_probably_private_reply(context, to_ids, from_id, mime_parser, parent_chat.id).await? { + // If the parent chat is a 1:1 chat, then the message should go to the 1:1 chat. + if to_ids.len() == 1 { + let name = chat::get_other_chat_contacts(context, parent_chat_id).await?[0]; + if from_id != *name { + mime_parser.set_override_sender_name(Some(name.get_stock_name(context).await)); + } + return Ok(Some((parent_chat.id, parent_chat.blocked))); + } return Ok(None); } diff --git a/src/stock_str.rs b/src/stock_str.rs index d03cc193d7..bf925d8fda 100644 --- a/src/stock_str.rs +++ b/src/stock_str.rs @@ -542,7 +542,7 @@ impl ContactId { } /// Get contact name, e.g. `Bob`, or `bob@exmple.net` if no name is set. - async fn get_stock_name(self, context: &Context) -> String { + pub async fn get_stock_name(self, context: &Context) -> String { Contact::get_by_id(context, self) .await .map(|contact| contact.get_display_name().to_string()) From 1c30daf4c2f35e66c74d19e9abc4925760445016 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sat, 2 Nov 2024 14:28:51 +0100 Subject: [PATCH 2/9] change export name from `DeltaChat` to `WebsocketDeltaChat` --- deltachat-jsonrpc/typescript/example/example.ts | 2 +- deltachat-jsonrpc/typescript/src/client.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/deltachat-jsonrpc/typescript/example/example.ts b/deltachat-jsonrpc/typescript/example/example.ts index e45bc18ccd..23eedfe4ad 100644 --- a/deltachat-jsonrpc/typescript/example/example.ts +++ b/deltachat-jsonrpc/typescript/example/example.ts @@ -1,4 +1,4 @@ -import { DcEvent, DeltaChat } from "../deltachat.js"; +import { DcEvent, WebsocketDeltaChat as DeltaChat } from "../deltachat.js"; var SELECTED_ACCOUNT = 0; diff --git a/deltachat-jsonrpc/typescript/src/client.ts b/deltachat-jsonrpc/typescript/src/client.ts index 83cc2f7e71..baa70d11f0 100644 --- a/deltachat-jsonrpc/typescript/src/client.ts +++ b/deltachat-jsonrpc/typescript/src/client.ts @@ -83,7 +83,7 @@ export const DEFAULT_OPTS: Opts = { url: "ws://localhost:20808/ws", startEventLoop: true, }; -export class DeltaChat extends BaseDeltaChat { +export class WebsocketDeltaChat extends BaseDeltaChat { opts: Opts; close() { this.transport.close(); From 77cd5b65430f29dd97ee2dfe97170bebba176043 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sat, 2 Nov 2024 14:40:04 +0100 Subject: [PATCH 3/9] export `Event` and `ContextEvents` type to include them in the documentation. --- deltachat-jsonrpc/typescript/src/client.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deltachat-jsonrpc/typescript/src/client.ts b/deltachat-jsonrpc/typescript/src/client.ts index baa70d11f0..f28fb5f55e 100644 --- a/deltachat-jsonrpc/typescript/src/client.ts +++ b/deltachat-jsonrpc/typescript/src/client.ts @@ -5,14 +5,14 @@ import { RawClient } from "../generated/client.js"; import { WebsocketTransport, BaseTransport, Request } from "yerpc"; import { TinyEmitter } from "@deltachat/tiny-emitter"; -type Events = { ALL: (accountId: number, event: EventType) => void } & { +export type Events = { ALL: (accountId: number, event: EventType) => void } & { [Property in EventType["kind"]]: ( accountId: number, event: Extract ) => void; }; -type ContextEvents = { ALL: (event: EventType) => void } & { +export type ContextEvents = { ALL: (event: EventType) => void } & { [Property in EventType["kind"]]: ( event: Extract ) => void; From d2fa6c437c57610de40bd1d61f803871ca36b445 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sat, 2 Nov 2024 14:42:18 +0100 Subject: [PATCH 4/9] dedicated readme for `@deltachat/jsonrpc-client`. so there is something more useful displayed on npm and on https://js.jsonrpc.delta.chat --- deltachat-jsonrpc/typescript/Readme.md | 68 ++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 deltachat-jsonrpc/typescript/Readme.md diff --git a/deltachat-jsonrpc/typescript/Readme.md b/deltachat-jsonrpc/typescript/Readme.md new file mode 100644 index 0000000000..7ed214ed5e --- /dev/null +++ b/deltachat-jsonrpc/typescript/Readme.md @@ -0,0 +1,68 @@ +# @deltachat/jsonrpc-client + +This package is a client for the jsonrpc server. + +> If you are looking for the functions in the documentation, they are under [`RawClient`](https://js.jsonrpc.delta.chat/classes/RawClient.html). + +### Important Terms + +- [delta chat core](https://github.com/deltachat/deltachat-core-rust/) the heart of all Delta Chat clients. Handels all the heavy lifting (email, encryption, ...) and provides an easy api for bots and clients (`getChatlist`, `getChat`, `getContact`, ...). +- [jsonrpc](https://www.jsonrpc.org/specification) is a json based protocol +for applications to speak to each other by [remote procedure calls](https://en.wikipedia.org/wiki/Remote_procedure_call) (short RPC), +which basically means that the client can call methods on the server by sending a json messages. +- [`deltachat-rpc-server`](https://github.com/deltachat/deltachat-core-rust/tree/main/deltachat-rpc-server) provides the jsonrpc api over stdio (stdin/stdout) +- [`@deltachat/stdio-rpc-server`](https://www.npmjs.com/package/@deltachat/stdio-rpc-server) is an easy way to install `deltachat-rpc-server` from npm and use it from nodejs. + +#### Transport +You need to connect this client to an instance of deltachat core via a transport. + +Currently there are 2 transports available: +- (recomended) `StdioTransport` usable from `StdioDeltaChat` - speak to `deltachat-rpc-server` directly +- `WebsocketTransport` usable from `WebsocketDeltaChat` + +You can also make your own transport, for example deltachat desktop uses a custom transport that sends the json messages over electron ipc. +Just implement your transport based on the `Transport` interface - look at how the [stdio transport is implemented](https://github.com/deltachat/deltachat-core-rust/blob/7121675d226e69fd85d0194d4b9c4442e4dd8299/deltachat-jsonrpc/typescript/src/client.ts#L113) for an example, it's not hard. + +## Usage + +> The **minimum** nodejs version for `@deltachat/stdio-rpc-server` is `16` + +``` +npm i @deltachat/stdio-rpc-server @deltachat/jsonrpc-client +``` + +```js +import { startDeltaChat } from "@deltachat/stdio-rpc-server"; +// Import constants you might need later +import { C } from "@deltachat/jsonrpc-client"; + +async function main() { + const dc = await startDeltaChat("deltachat-data"); + console.log(await dc.rpc.getSystemInfo()); + dc.close() +} +main() +``` + +For a more complete example refer to . + +### Listening for events + +```ts +dc.on("Info", (accountId, { msg }) => + console.info(accountId, "[core:info]", msg) +); +// Or get an event emitter for only one account +const emitter = dc.getContextEvents(accountId) +emitter.on("IncomingMsg", async ({chatId, msgId}) => { + const message = await dc.rpc.getMessage(accountId, msgId) + console.log("got message in chat "+chatId+" : ", message.text) +}) +``` + +## Further information + +- `@deltachat/stdio-rpc-server` + - [package on npm](https://www.npmjs.com/package/@deltachat/stdio-rpc-server) + - [source code on github](https://github.com/deltachat/deltachat-core-rust/tree/main/deltachat-rpc-server/npm-package) +- [use `@deltachat/stdio-rpc-server` on an usuported platform](https://github.com/deltachat/deltachat-core-rust/tree/main/deltachat-rpc-server/npm-package#how-to-use-on-an-unsupported-platform) \ No newline at end of file From 35168eec81410fd7fad3ec7f5bf06c417261f06d Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sat, 2 Nov 2024 14:42:45 +0100 Subject: [PATCH 5/9] update link to echo bot in deltachat-rpc-server --- deltachat-rpc-server/npm-package/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deltachat-rpc-server/npm-package/README.md b/deltachat-rpc-server/npm-package/README.md index cd7594b095..4ce994353c 100644 --- a/deltachat-rpc-server/npm-package/README.md +++ b/deltachat-rpc-server/npm-package/README.md @@ -25,7 +25,7 @@ async function main() { main() ``` -For a more complete example refer to https://github.com/deltachat-bot/echo/pull/69/files (TODO change link when pr is merged). +For a more complete example refer to https://github.com/deltachat-bot/echo/tree/master/nodejs_stdio_jsonrpc. ## How to use on an unsupported platform From f302ce92deaa26d0300c0e39bbc85491329b085e Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sat, 2 Nov 2024 14:52:40 +0100 Subject: [PATCH 6/9] update deltachat-jsonrpc readme --- deltachat-jsonrpc/README.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/deltachat-jsonrpc/README.md b/deltachat-jsonrpc/README.md index 7e8110652f..bbbd40c0f2 100644 --- a/deltachat-jsonrpc/README.md +++ b/deltachat-jsonrpc/README.md @@ -52,16 +52,34 @@ npm install npm run build ``` -The JavaScript client is not yet published on NPM (but will likely be soon). Currently, it is recommended to vendor the bundled build. After running `npm run build` as documented above, there will be a file `dist/deltachat.bundle.js`. This is an ESM module containing all dependencies. Copy this file to your project and import the DeltaChat class. +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 { DeltaChat } from './deltachat.bundle.js' +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() +``` + +Websocket: +```typescript +import { WebsocketDeltaChat as DeltaChat } from '@deltachat/jsonrpc-client''= + const dc = new DeltaChat('ws://localhost:20808/ws') +console.log(await dc.rpc.getSystemInfo()); const accounts = await dc.rpc.getAllAccounts() console.log('accounts', accounts) ``` +##### Generate TypeScript/JavaScript documentation + A script is included to build autogenerated documentation, which includes all RPC methods: ```sh cd typescript @@ -104,7 +122,7 @@ cd typescript npm run test ``` -This will build the `deltachat-jsonrpc-server` binary and then run a test suite against the WebSocket server. +This will build the `deltachat-rpc-server` binary and then run a test suite against the deltachat-rpc-server (stdio). The test suite includes some tests that need online connectivity and a way to create test email accounts. To run these tests, talk to DeltaChat developers to get a token for the `testrun.org` service, or use a local instance of [`mailadm`](https://github.com/deltachat/docker-mailadm). From aff063e893dd1748a97344edc838bbd8d7c74180 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sat, 2 Nov 2024 14:53:49 +0100 Subject: [PATCH 7/9] run prettier formatter on some readme files --- deltachat-jsonrpc/README.md | 29 ++++++++++++++-------- deltachat-rpc-server/npm-package/README.md | 10 ++++---- 2 files changed, 23 insertions(+), 16 deletions(-) diff --git a/deltachat-jsonrpc/README.md b/deltachat-jsonrpc/README.md index bbbd40c0f2..80ed414e84 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 4ce994353c..f92adadc86 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. From 85d5b7b8359fe9baffc2dce0156a756437d3a894 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sat, 2 Nov 2024 15:13:31 +0100 Subject: [PATCH 8/9] add instructions on how to use on an unsupported platform --- deltachat-rpc-server/npm-package/README.md | 30 ++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/deltachat-rpc-server/npm-package/README.md b/deltachat-rpc-server/npm-package/README.md index f92adadc86..aacf01c17d 100644 --- a/deltachat-rpc-server/npm-package/README.md +++ b/deltachat-rpc-server/npm-package/README.md @@ -29,9 +29,35 @@ For a more complete example refer to https://github.com/deltachat-bot/echo/tree/ ## How to use on an unsupported platform - +You need to have rust installed to compile deltachat core for your platform and cpu architecture. + is the recommended way to install rust. +Also your system probably needs more than 4gb ram to compile core, alternatively your could try to build the debug build, that might take less ram to build. - +1. clone the core repo, right next to your project folder: `git clone git@github.com:deltachat/deltachat-core-rust.git` +2. go into your core checkout and run `git pull` and `git checkout ` to point it to the correct version (needs to be the same version the `@deltachat/jsonrpc-client` package has) +3. run `cargo build --release --package deltachat-rpc-server --bin deltachat-rpc-server` + +Then you have 2 options: + +### point to deltachat-rpc-server via direct path: + +```sh +# start your app with the DELTA_CHAT_RPC_SERVER env var +DELTA_CHAT_RPC_SERVER="../deltachat-core-rust/target/release/deltachat-rpc-server" node myapp.js +``` + +### install deltachat-rpc-server in your $PATH: + +```sh +# use this to install to ~/.cargo/bin +cargo install --release --package deltachat-rpc-server --bin deltachat-rpc-server +# or manually move deltachat-core-rust/target/release/deltachat-rpc-server +# to a location that is included in your $PATH Environment variable. +``` + +```js +startDeltaChat("data-dir", { takeVersionFromPATH: true }); +``` ## How does it work when you install it From 6ab5c4f6b5041603581a10ce232e5683c54acaf1 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sat, 2 Nov 2024 18:36:46 +0100 Subject: [PATCH 9/9] adapt Getting Started tutorial from cffi documentation --- deltachat-jsonrpc/typescript/Readme.md | 144 ++++++++++++++++++++++--- 1 file changed, 132 insertions(+), 12 deletions(-) diff --git a/deltachat-jsonrpc/typescript/Readme.md b/deltachat-jsonrpc/typescript/Readme.md index 7ed214ed5e..8c2e66957b 100644 --- a/deltachat-jsonrpc/typescript/Readme.md +++ b/deltachat-jsonrpc/typescript/Readme.md @@ -8,15 +8,17 @@ This package is a client for the jsonrpc server. - [delta chat core](https://github.com/deltachat/deltachat-core-rust/) the heart of all Delta Chat clients. Handels all the heavy lifting (email, encryption, ...) and provides an easy api for bots and clients (`getChatlist`, `getChat`, `getContact`, ...). - [jsonrpc](https://www.jsonrpc.org/specification) is a json based protocol -for applications to speak to each other by [remote procedure calls](https://en.wikipedia.org/wiki/Remote_procedure_call) (short RPC), -which basically means that the client can call methods on the server by sending a json messages. + for applications to speak to each other by [remote procedure calls](https://en.wikipedia.org/wiki/Remote_procedure_call) (short RPC), + which basically means that the client can call methods on the server by sending a json messages. - [`deltachat-rpc-server`](https://github.com/deltachat/deltachat-core-rust/tree/main/deltachat-rpc-server) provides the jsonrpc api over stdio (stdin/stdout) - [`@deltachat/stdio-rpc-server`](https://www.npmjs.com/package/@deltachat/stdio-rpc-server) is an easy way to install `deltachat-rpc-server` from npm and use it from nodejs. #### Transport + You need to connect this client to an instance of deltachat core via a transport. Currently there are 2 transports available: + - (recomended) `StdioTransport` usable from `StdioDeltaChat` - speak to `deltachat-rpc-server` directly - `WebsocketTransport` usable from `WebsocketDeltaChat` @@ -37,11 +39,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 . @@ -50,19 +52,137 @@ For a more complete example refer to - console.info(accountId, "[core:info]", msg) + console.info(accountId, "[core:info]", msg) ); // Or get an event emitter for only one account -const emitter = dc.getContextEvents(accountId) -emitter.on("IncomingMsg", async ({chatId, msgId}) => { - const message = await dc.rpc.getMessage(accountId, msgId) - console.log("got message in chat "+chatId+" : ", message.text) +const emitter = dc.getContextEvents(accountId); +emitter.on("IncomingMsg", async ({ chatId, msgId }) => { + const message = await dc.rpc.getMessage(accountId, msgId); + console.log("got message in chat " + chatId + " : ", message.text); +}); +``` + +### Getting Started + +This section describes how to handle the Delta Chat core library over the jsonrpc bindings. +For general information about Delta Chat itself, +see and . + +Let's start. + +First of all, you have to start the deltachat-rpc-server process. + +```js +import { startDeltaChat } from "@deltachat/stdio-rpc-server"; +const dc = await startDeltaChat("deltachat-data"); +``` + +Then we have to create an Account (also called Context or profile) that is bound to a database. +The database is a normal SQLite file with a "blob directory" beside it. +But these details are handled by deltachat's account manager. +So you just have to tell the account manager to create a new account: + +```js +const accountId = await dc.rpc.addAccount(); +``` + +After that, register event listeners so you can see what core is doing: +Intenally `@deltachat/jsonrpc-client` implments a loop that waits for new events and then emits them to javascript land. +```js +dc.on("Info", (accountId, { msg }) => + console.info(accountId, "[core:info]", msg) +); +``` + +Now you can **configure the account:** +```js +// use some real test credentials here +await dc.rpc.setConfig(accountId, "addr", "alice@example.org") +await dc.rpc.setConfig(accountId, "mail_pw", "***") +// you can also set multiple config options in one call +await dc.rpc.batchSetConfig(accountId, { + "addr": "alice@example.org", + "mail_pw": "***" }) + +// after setting the credentials attempt to login +await dc.rpc.configure(accountId) ``` +`configure()` returns a promise that is rejected on error (with await is is thrown). +The configuration itself may take a while. You can monitor it's progress like this: +```js +dc.on("ConfigureProgress", (accountId, { progress, comment }) => { + console.log(accountId, "ConfigureProgress", progress, comment); +}); +// make sure to register this event handler before calling `dc.rpc.configure()` +``` + +The configuration result is saved in the database. +On subsequent starts it is not needed to call `dc.rpc.configure(accountId)` +(you can check this using `dc.rpc.isConfigured(accountId)`). + +On a successfully configuration delta chat core automatically connects to the server, however subsequent starts you **need to do that manually** by calling `dc.rpc.startIo(accountId)` or `dc.rpc.startIoForAllAccounts()`. + +```js +if (!await dc.rpc.isConfigured(accountId)) { + // use some real test credentials here + await dc.rpc.batchSetConfig(accountId, { + "addr": "alice@example.org", + "mail_pw": "***" + }) + await dc.rpc.configure(accountId) +} else { + await dc.rpc.startIo(accountId) +} +``` + +Now you can **send the first message:** + +```js +const contactId = await dc.rpc.createContact(accountId, "bob@example.org", null /* optional name */) +const chatId = await dc.rpc.createChatByContactId(accountId, contactId) + +await dc.rpc.miscSendTextMessage(accountId, chatId, "Hi, here is my first message!") +``` + +`dc.rpc.miscSendTextMessage()` returns immediately; +the sending itself is done in the background. +If you check the testing address (bob), +you should receive a normal e-mail. +Answer this e-mail in any e-mail program with "Got it!", +and the IO you started above will **receive the message**. + +You can then **list all messages** of a chat as follows: + +```js +let i = 0; +for (const msgId of await exp.rpc.getMessageIds(120, 12, false, false)) { + i++; + console.log(`Message: ${i}`, (await dc.rpc.getMessage(120, msgId)).text); +} +``` + +This will output the following two lines: +``` +Message 1: Hi, here is my first message! +Message 2: Got it! +``` + + + ## Further information - `@deltachat/stdio-rpc-server` - [package on npm](https://www.npmjs.com/package/@deltachat/stdio-rpc-server) - [source code on github](https://github.com/deltachat/deltachat-core-rust/tree/main/deltachat-rpc-server/npm-package) -- [use `@deltachat/stdio-rpc-server` on an usuported platform](https://github.com/deltachat/deltachat-core-rust/tree/main/deltachat-rpc-server/npm-package#how-to-use-on-an-unsupported-platform) \ No newline at end of file +- [use `@deltachat/stdio-rpc-server` on an usuported platform](https://github.com/deltachat/deltachat-core-rust/tree/main/deltachat-rpc-server/npm-package#how-to-use-on-an-unsupported-platform) +- The issue-tracker for the core library is here: + +If you need further assistance, +please do not hesitate to contact us +through the channels shown at https://delta.chat/en/contribute + +Please keep in mind, that your derived work +must respect the Mozilla Public License 2.0 of deltachat-rpc-server +and the respective licenses of the libraries deltachat-rpc-server links with. \ No newline at end of file