From 329f498651d7ed7ddeb42a89308c6d403ee9bd48 Mon Sep 17 00:00:00 2001 From: "Franz Heinzmann (Frando)" Date: Wed, 29 Jun 2022 17:53:45 +0200 Subject: [PATCH] improve docs, fix example --- deltachat-jsonrpc/README.md | 25 ++++++++--- deltachat-jsonrpc/typescript/.gitignore | 2 + .../typescript/example/example.ts | 45 ++++++++----------- .../typescript/example/node-add-account.js | 26 +++++++++++ deltachat-jsonrpc/typescript/package.json | 12 ++--- 5 files changed, 72 insertions(+), 38 deletions(-) create mode 100644 deltachat-jsonrpc/typescript/example/node-add-account.js diff --git a/deltachat-jsonrpc/README.md b/deltachat-jsonrpc/README.md index e5f12caa9..f1969d8db 100644 --- a/deltachat-jsonrpc/README.md +++ b/deltachat-jsonrpc/README.md @@ -27,16 +27,29 @@ If you are targetting other architectures (like KaiOS or Android), the webserver cross build --features=webserver --target armv7-linux-androideabi --release ``` +### Using the typescript client + +The package includes TypeScript bindings which are 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 client is also published on npm as `@deltachat/jsonrpc-client`. + +To use it locally, first install the dependencies and compile the TypeScript code to JavaScript: +```sh +cd typescript +npm install +npm run build +``` + +You can also build autogenerated documentation, including all RPC methods: +```sh +cd typescript +npm run docs +``` +Now, open the [`typescript/docs`](typescript/docs) folder in a web browser. + + ### Running the example app We include a small demo web application that talks to the WebSocket server. To run it, follow these steps: -* The package includes TypeScript bindings which are partially auto-generated through the JSON-RPC library used by this crate ([yerpc](https://github.com/Frando/yerpc/)). - ```sh - cd typescript - npm install - npm run build - ``` * Then, build and run the example application: ```sh diff --git a/deltachat-jsonrpc/typescript/.gitignore b/deltachat-jsonrpc/typescript/.gitignore index 98d74b443..ca2372bc1 100644 --- a/deltachat-jsonrpc/typescript/.gitignore +++ b/deltachat-jsonrpc/typescript/.gitignore @@ -4,3 +4,5 @@ test_dist coverage yarn.lock package-lock.json +docs +accounts diff --git a/deltachat-jsonrpc/typescript/example/example.ts b/deltachat-jsonrpc/typescript/example/example.ts index f13d3a717..f543a51cf 100644 --- a/deltachat-jsonrpc/typescript/example/example.ts +++ b/deltachat-jsonrpc/typescript/example/example.ts @@ -1,7 +1,5 @@ -import { RawClient } from "../src/lib"; -import { WebsocketTransport, Request } from "yerpc"; +import { Deltachat, DeltachatEvent } from "../deltachat.js"; -type DeltaEvent = { id: string; contextId: number; field1: any; field2: any }; var SELECTED_ACCOUNT = 0; window.addEventListener("DOMContentLoaded", (_event) => { @@ -9,6 +7,7 @@ window.addEventListener("DOMContentLoaded", (_event) => { SELECTED_ACCOUNT = Number(id); window.dispatchEvent(new Event("account-changed")); }; + console.log('launch run script...') run().catch((err) => console.error("run failed", err)); }); @@ -17,31 +16,24 @@ async function run() { const $side = document.getElementById("side")!; const $head = document.getElementById("header")!; - const transport = new WebsocketTransport("ws://localhost:20808/ws"); - const client = new RawClient(transport); - transport.on("error", (err) => { - console.error("WebSocket transport error", err) - }); + const client = new Deltachat('ws://localhost:20808/ws') - ;(window as any).client = client; + ;(window as any).client = client.rpc; - transport.on("request", (request: Request) => { - const method = request.method; - if (method === "event") { - const params = request.params! as DeltaEvent; - onIncomingEvent(params, params.id); - } - }); + client.on("ALL", event => { + onIncomingEvent(event) + }) window.addEventListener("account-changed", async (_event: Event) => { - await client.selectAccount(SELECTED_ACCOUNT); listChatsForSelectedAccount(); }); await Promise.all([loadAccountsInHeader(), listChatsForSelectedAccount()]); async function loadAccountsInHeader() { - const accounts = await client.getAllAccounts(); + console.log('load accounts') + const accounts = await client.rpc.getAllAccounts(); + console.log('accounts loaded', accounts) for (const account of accounts) { if (account.type === "Configured") { write( @@ -63,31 +55,30 @@ async function run() { async function listChatsForSelectedAccount() { clear($main); - const selectedAccount = await client.getSelectedAccountId(); - if (!selectedAccount) return write($main, "No account selected"); - const info = await client.getAccountInfo(selectedAccount); + const selectedAccount = SELECTED_ACCOUNT + const info = await client.rpc.getAccountInfo(selectedAccount); if (info.type !== "Configured") { return write($main, "Account is not configured"); } write($main, `

${info.addr!}

`); - const chats = await client.getChatlistEntries( + const chats = await client.rpc.getChatlistEntries( selectedAccount, 0, null, null ); for (const [chatId, _messageId] of chats) { - const chat = await client.chatlistGetFullChatById( + const chat = await client.rpc.chatlistGetFullChatById( selectedAccount, chatId ); write($main, `

${chat.name}

`); - const messageIds = await client.messageListGetMessageIds( + const messageIds = await client.rpc.messageListGetMessageIds( selectedAccount, chatId, 0 ); - const messages = await client.messageGetMessages( + const messages = await client.rpc.messageGetMessages( selectedAccount, messageIds ); @@ -97,12 +88,12 @@ async function run() { } } - function onIncomingEvent(event: DeltaEvent, name: string) { + function onIncomingEvent(event: DeltachatEvent) { write( $side, `

- [${name} on account ${event.contextId}]
+ [${event.id} on account ${event.contextId}]
f1: ${JSON.stringify(event.field1)}
f2: ${JSON.stringify(event.field2)}

` diff --git a/deltachat-jsonrpc/typescript/example/node-add-account.js b/deltachat-jsonrpc/typescript/example/node-add-account.js new file mode 100644 index 000000000..d8299d23c --- /dev/null +++ b/deltachat-jsonrpc/typescript/example/node-add-account.js @@ -0,0 +1,26 @@ +import { Deltachat } from "../dist/deltachat.js"; + +run().catch(console.error); + +async function run() { + const delta = new Deltachat('ws://localhost:20808/ws'); + delta.on("event", (event) => { + console.log("event", event.data); + }); + + const email = process.argv[2] + const password = process.argv[3] + if (!email || !password) throw new Error('USAGE: node node-add-account.js ') + console.log(`creating acccount for ${email}`) + const id = await delta.rpc.addAccount() + console.log(`created account id ${id}`) + await delta.rpc.setConfig(id, "addr", email); + await delta.rpc.setConfig(id, "mail_pw", password); + console.log('configuration updated') + await delta.rpc.configure(id) + console.log('account configured!') + + const accounts = await delta.rpc.getAllAccounts(); + console.log("accounts", accounts); + console.log("waiting for events...") +} diff --git a/deltachat-jsonrpc/typescript/package.json b/deltachat-jsonrpc/typescript/package.json index 370fcde65..753802a56 100644 --- a/deltachat-jsonrpc/typescript/package.json +++ b/deltachat-jsonrpc/typescript/package.json @@ -12,11 +12,12 @@ "build": "npm run generate-bindings && tsc", "bundle": "npm run build && esbuild --bundle dist/deltachat.js --outfile=dist/deltachat.bundle.js", "generate-bindings": "cargo test", - "example:build": "tsc && esbuild --bundle dist/example.js --outfile=dist/example.bundle.js && cp example/index.html dist", - "example:start": "http-server dist/", + "example:build": "tsc && esbuild --bundle dist/example/example.js --outfile=dist/example.bundle.js", + "example:start": "http-server .", "example:dev": "esbuild example/example.ts --bundle --outfile=dist/example.bundle.js --servedir=.", "coverage": "tsc -b test && COVERAGE=1 NODE_OPTIONS=--enable-source-maps c8 --include \"dist/*\" -r text -r html -r json mocha test_dist && node report_api_coverage.mjs", - "test": "rm -rf dist && npm run build && npm run coverage && npm run prettier:check" + "test": "rm -rf dist && npm run build && npm run coverage && npm run prettier:check", + "docs": "typedoc --out docs deltachat.ts" }, "dependencies": { "isomorphic-ws": "^4.0.1", @@ -24,8 +25,6 @@ "yerpc": "^0.3.3" }, "devDependencies": { - "prettier": "^2.6.2", - "chai-as-promised": "^7.1.1", "@types/chai": "^4.2.21", "@types/chai-as-promised": "^7.1.5", "@types/mocha": "^9.0.0", @@ -33,9 +32,12 @@ "@types/ws": "^7.2.4", "c8": "^7.10.0", "chai": "^4.3.4", + "chai-as-promised": "^7.1.1", "esbuild": "^0.14.11", "mocha": "^9.1.1", "node-fetch": "^2.6.1", + "prettier": "^2.6.2", + "typedoc": "^0.23.2", "typescript": "^4.5.5", "ws": "^8.5.0" }