Update docs to match @session.js/client@0.0.57
This commit is contained in:
parent
0b9147d7b8
commit
2d1e10e89c
11 changed files with 52 additions and 31 deletions
21
LICENSE
Normal file
21
LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2026 Viktor Shchelochkov <hi@hloth.dev> (https://hloth.dev)
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
12
README.md
12
README.md
|
|
@ -1,13 +1,17 @@
|
|||
# Session.js documentation website
|
||||
|
||||
[](https://sessionjs.github.io/docs)
|
||||
[](https://sessionjs.github.io/docs)
|
||||
|
||||
[Visit documentation website](https://sessionjs.github.io/docs)
|
||||
|
||||
## Made for session.js
|
||||
## Made for Session.js
|
||||
|
||||
Use Session messenger programmatically with [Session.js](https://github.com/sessionjs/client): Session bots, custom Session clients, and more.
|
||||
Use Session messenger programmatically with [Session.js](https://git.hloth.dev/session.js/client): Session bots, custom Session clients, and more.
|
||||
|
||||
## Donate
|
||||
|
||||
[hloth.dev/donate](https://hloth.dev/donate)
|
||||
[hloth.dev/donate](https://hloth.dev/donate) · Tor: [hlothdevzkti6suoksy7lcy7hmpxnr3msu5waokzaslsi2mnx5ouu4qd.onion/donate](http://hlothdevzkti6suoksy7lcy7hmpxnr3msu5waokzaslsi2mnx5ouu4qd.onion/donate)
|
||||
|
||||
## License
|
||||
|
||||
[MIT](./LICENSE)
|
||||
|
|
@ -4,13 +4,13 @@ Friendly reminder: this package can't be used and won't work with Node.js.
|
|||
|
||||
## Installation
|
||||
|
||||
By using this software, you are agreeing to abide by [Terms of use](https://github.com/sessionjs/client/blob/main/TERMS.md). Shortly: no abuse and spam, you're solely responsible for your actions with this software.
|
||||
By using this software, you are agreeing to abide by [Terms of use](https://git.hloth.dev/session.js/client/blob/main/TERMS.md). Shortly: no abuse and spam, you're solely responsible for your actions with this software.
|
||||
|
||||
1. First install bun: https://bun.sh/
|
||||
2. Create a new Bun project in any directory, using `bun init` or manually
|
||||
3. Install session.js: `bun add @session.js/client`
|
||||
|
||||
Always make sure to await for initialization of library:
|
||||
Make sure to await for initialization of library before calling any methods:
|
||||
|
||||
```ts
|
||||
import { ready } from '@session.js/client'
|
||||
|
|
@ -19,8 +19,6 @@ await ready
|
|||
// ...
|
||||
```
|
||||
|
||||
Otherwise you might get errors like `sodium.crypto_sign_seed_keypair is not a function`
|
||||
|
||||
## Quick start
|
||||
|
||||
### Sending messages
|
||||
|
|
@ -112,7 +110,7 @@ session.on('message', (msg: Message) => {
|
|||
|
||||
## Examples
|
||||
|
||||
You can find fully complete examples in [examples repository](https://github.com/sessionjs/examples/)
|
||||
You can find fully complete examples in [examples repository](https://git.hloth.dev/session.js/examples/)
|
||||
|
||||
- [Simple example](https://github.com/sessionjs/examples/tree/main/simple)
|
||||
- [Browser](https://github.com/sessionjs/examples/tree/main/browser-simple)
|
||||
- [Simple example](https://git.hloth.dev/session.js/examples/tree/main/simple)
|
||||
- [Browser](https://git.hloth.dev/session.js/examples/tree/main/browser-simple)
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
Session.js is JavaScript library for programmatic usage of [Session messenger by OXEN](https://getsession.org). Supports server and browser environment with built-in proxy network module. Shipped with TypeScript definitions. Tested with bun:test. Written with blazingly fast [Bun](https://bun.sh), a modern runtime for JavaScript and alternative to Node.js. **This package cannot be used with Node.js, it uses a better runtime instead of it**. It can also be used with most bundlers that support modern syntax.
|
||||
Session.js is JavaScript library for programmatic usage of [Session messenger by OXEN](https://getsession.org). Supports server and browser environment with built-in proxy network module. Shipped with TypeScript definitions. Tested with bun:test. It's aimed for [Bun](https://bun.sh) users — a modern runtime for JavaScript and alternative to Node.js. But it can also be used on most platforms and runtimes thanks to external modules system and platform-agnostic architecture with vanilla [noble](https://paulmillr.com/noble/) cryptography instead of WASM-compiled libsodium and bytebuffer.
|
||||
|
||||
Session.js allows you to create:
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ Session.js allows you to create:
|
|||
|
||||
- On-demand polling — you decide when to get new messages and whether instance should poll them (and poll settings like frequency) or work just for sending
|
||||
- Per-instance storage and network settings — you can attach persistant storage to instance or use in-memory storage for throwaway one-time instances
|
||||
- Session.js can be used in browser, keeping private keys on client-side and doing network requests on server-side. See this in action with [my full-featured Session Web client](https://github.com/VityaSchel/session-web)!
|
||||
- Session.js can be used in browser, keeping private keys on client-side and doing network requests on server-side. See this in action with [my full-featured Session Web client](https://git.hloth.dev/hloth/session-web)!
|
||||
|
||||
## Getting started
|
||||
|
||||
|
|
@ -54,13 +54,12 @@ Jump to [getting started](./getting-started.md) page to start using Session.js!
|
|||
- [X] Avatar
|
||||
- [X] Syncing between devices
|
||||
- [X] ONS resolving
|
||||
- [ ] Get rid of ByteBuffer and other lazy dependencies
|
||||
|
||||
</details>
|
||||
|
||||
## License
|
||||
|
||||
All code in Session.js (including any submodules) was written by Viktor Shchelochkov aka hloth and licensed under [MIT license](https://github.com/sessionjs/client/blob/main/LICENSE.md)
|
||||
All code in Session.js (including any submodules) was written by Viktor Shchelochkov aka hloth and licensed under [MIT license](https://git.hloth.dev/session.js/client/blob/main/LICENSE.md)
|
||||
|
||||
## Funding
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ You can pick existing network connector or [write your own](#creating-new-networ
|
|||
<tr>
|
||||
<td><a href="./bun-remote">Bun (remote) for proxies</a></td>
|
||||
<td>❌</td>
|
||||
<td> This network might be useful if you're building client in environment that does not allow you sending requests to Session nodes with self-signed certificates. This option is ideal for browser clients, because it handles all network connection on backend proxy that forwards client-side encrypted data to snodes. Check out simple <a href="https://github.com/sessionjs/examples">browser example here</a>. </td>
|
||||
<td> This network might be useful if you're building client in environment that does not allow you sending requests to Session nodes with self-signed certificates. This option is ideal for browser clients, because it handles all network connection on backend proxy that forwards client-side encrypted data to snodes. Check out simple <a href="https://git.hloth.dev/session.js/examples">browser example here</a>. </td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
|
|
|||
|
|
@ -19,19 +19,19 @@ You can pick any of them to request service nodes list and preferrably add mecha
|
|||
|
||||
All requests to swarms, service nodes, and seed nodes are made using JSON RPC format. All of them have their own self-signed certificate. For seed nodes, you should implement "certificate pinning", i.e. hardcode seeds servers certificates data directly in your code for maximum security. For service nodes and swarms, you will receive their certificates data in list requests.
|
||||
|
||||
[@session.js/client](https://github.com/sessionjs/client) handles all that logic for you. You can simply pass Session ID and message and it will send the message for you. Additionally, there is getSwarm method that does everything described above but returns swarm's ip address and port for your custom logic.
|
||||
[@session.js/client](https://git.hloth.dev/session.js/client) handles all that logic for you. You can simply pass Session ID and message and it will send the message for you. Additionally, there is getSwarm method that does everything described above but returns swarm's ip address and port for your custom logic.
|
||||
|
||||
## How does storing messages on Swarms work?
|
||||
|
||||
As said previously, you have to find swarm for specific Session ID. Do not mistake it with your own swarm: when you want to send message to recipient, you should find and use recipient's swarm. Since Session is built on top of Signal protocol, it uses Signal's protobuf schema and Signal's messages classes to serialize message data and encrypt it locally using private key. Then it uses `store` method to save message in swarm storage.
|
||||
|
||||
[@session.js/client](https://github.com/sessionjs/client) allows you to create any number of instances in single JavaScript file that can send as many messages as you want with a simple yet flexible API.
|
||||
[@session.js/client](https://git.hloth.dev/session.js/client) allows you to create any number of instances in single JavaScript file that can send as many messages as you want with a simple yet flexible API.
|
||||
|
||||
## How does messages polling work?
|
||||
|
||||
Similar to messages storing, to poll messages Session client would first find working service node using seed nodes, then ask for swarm for that specific Session ID (pubkey) and make frequent JSON RPC requests with `retrieve` method to get messages. To keep track of new messages, you'll typically use last hashes parameter. While messages in Session do have a unique identifier that is unique across all clients — hash, it looks like it either had been added too late or borrowed from Signal, because many interactions that refer to specific message (such as reply to previously sent message, messages deletion etc) use timestamp instead of hash. You'll mostly use messages hashes only for polling-related logic.
|
||||
|
||||
[@session.js/client](https://github.com/sessionjs/client) wraps polling into a simple interface, at the same time allowing you to customize polling as you want with all encryption and low-level logic encapsulated and processed by the library.
|
||||
[@session.js/client](https://git.hloth.dev/session.js/client) wraps polling into a simple interface, at the same time allowing you to customize polling as you want with all encryption and low-level logic encapsulated and processed by the library.
|
||||
|
||||
## How do you delete messages in Session?
|
||||
|
||||
|
|
|
|||
|
|
@ -13,12 +13,12 @@ Session ID is your inbox address which is [x25519 32 bytes public key aka Curve2
|
|||
Using @session.js/mnemonic and @session.js/keypair you can quickly generate random seeds, convert them to keypairs used by Session, get x25519 public key from it and encode to mnemonic that can be used in Session client.
|
||||
|
||||
```ts
|
||||
import { generateSeedHex, getKeypairFromSeed } from '@session.js/keypair'
|
||||
import { generateSeedHex, getKeysFromSeed } from '@session.js/keypair'
|
||||
import { encode } from '@session.js/mnemonic'
|
||||
|
||||
const seedHex = generateSeedHex() // generate random 16 bytes seed that should be kept secure
|
||||
const keypair = getKeypairFromSeed(seedHex) // derive public and private x25519 and ed25519 keys
|
||||
const sessionID = keypair.x25519.publicKey // Session ID is x25519 public key
|
||||
const keys = getKeysFromSeed(seedHex) // derive public and private x25519 and ed25519 keys
|
||||
const sessionId = keys.x25519.publicKey // Session ID is x25519 public key
|
||||
const mnemonic = encode(seedHex) // mnemonic is 13 words for accessing your Session
|
||||
```
|
||||
|
||||
|
|
@ -26,7 +26,7 @@ const mnemonic = encode(seedHex) // mnemonic is 13 words for accessing your Sess
|
|||
|
||||
Since there are no accounts, you can't register. Instead, your device generates a random private key (which can be displayed as encoded mnemonic), which is then converted to public key (which can be displayed as hex which is your Session ID). Public key allow another person to encrypt message, private key allows you to decrypt message. Obviously, you share public key (Session ID) so that other people can write you messages and never share private key (so that no one can read your messages except you).
|
||||
|
||||
[@session.js/client](https://github.com/sessionjs/client) handles all encryption logic for you.
|
||||
[@session.js/client](https://git.hloth.dev/session.js/client) handles all encryption logic for you.
|
||||
|
||||
## How to delete account in Session?
|
||||
|
||||
|
|
@ -40,7 +40,7 @@ As said above, a person must have your public key (Session ID) to send you a mes
|
|||
|
||||
Usernames are a popular way to access each other's chats without remembering whole address. They are unique and simply act as a link to full address. Session has its own usernames system called Oxen Name System (ONS) which allows you to buy a mapping to your Session ID (plus a few other integrated lokinet projects) for 7 OXEN which at time of writing this article is about 1$. Payments are processed inside of Oxen blockchain, which makes it secure. ONS deserves whole another article, so for now just keep in mind that you can buy username in Session which simply acts like a link to your Session ID.
|
||||
|
||||
[@session.js/ons](https://github.com/sessionjs/ons) handles resolving ONS->Session ID encryption logic for you, so you just have to provide ONS and you'll receive Session ID.
|
||||
[@session.js/ons](https://git.hloth.dev/session.js/ons) handles resolving ONS->Session ID encryption logic for you, so you just have to provide ONS and you'll receive Session ID.
|
||||
Alternatively, there is [https://ons.sessionbots.directory/](https://ons.sessionbots.directory/) which is a registry of ONS names with local client-side quick search among all registered ONS names in Session network.
|
||||
|
||||
## How Session profiles work?
|
||||
|
|
|
|||
|
|
@ -36,8 +36,7 @@ Just like regular attachments, avatars size is limited to 10 mb. It is recommend
|
|||
|
||||
```ts
|
||||
const filename = '/Users/kitty/Desktop/avatar.jpeg'
|
||||
const file = await fs.readFile(filename)
|
||||
const avatar: ArrayBuffer = file.buffer
|
||||
const avatar = await Bun.file(filename).bytes()
|
||||
|
||||
await session.setAvatar(avatar)
|
||||
```
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
SOGS (Session Open Group Server) is a type of Session communication channel, a community of users (with no limit on number of participants). It's not hosted on Session nodes, in contrast to Session groups, instead it is hosted on SOGS owner's server, but it is onion routed and end-to-end encrypted. If allows flexible management of rights and can be used for public announcements channels and chats.
|
||||
|
||||
Looking for a way to host SOGS yourself? Check out [bunsogs](https://github.com/vityaSchel/bunsogs/) from author of Session.js
|
||||
Looking for a way to host SOGS yourself? Check out [bunsogs](https://git.hloth.dev/hloth/bunsogs/)
|
||||
|
||||
## Interacting with SOGS
|
||||
|
||||
|
|
@ -149,7 +149,7 @@ const sogsPublicKey = '8948f2d9046a40e7dbc0a4fd7c29d8a4fe97df1fa69e64f0ab6fc317a
|
|||
|
||||
// Use blinding to hide your Session ID from others
|
||||
// Blinding uses ID unique to each SOGS so that no one knows your Session ID
|
||||
// (at least in theory, see https://github.com/VityaSchel/blinded-id-converter-website)
|
||||
// (at least in theory, see https://git.hloth.dev/hloth/blinded-id-converter-website)
|
||||
const blind = true
|
||||
|
||||
const msg = new VisibleMessage({
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
site_name: Session.js Docs
|
||||
site_url: https://sessionjs.github.io/docs
|
||||
repo_url: https://github.com/sessionjs/docs
|
||||
repo_url: https://git.hloth.dev/session.js/docs
|
||||
repo_name: sessionjs/client
|
||||
theme:
|
||||
name: material
|
||||
|
|
@ -24,10 +24,10 @@ copyright: Created by Viktor Shchelochkov aka <a href="https://hloth.dev" target
|
|||
extra:
|
||||
social:
|
||||
- icon: material/pencil
|
||||
link: https://github.com/sessionjs/docs
|
||||
link: https://git.hloth.dev/session.js/docs
|
||||
name: Edit documentation on GitHub
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/sessionjs
|
||||
link: https://git.hloth.dev/session.js
|
||||
name: Session.js on GitHub
|
||||
- icon: fontawesome/brands/telegram
|
||||
link: https://t.me/sessionjs
|
||||
|
|
|
|||
BIN
screenshot.avif
Normal file
BIN
screenshot.avif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
Loading…
Add table
Add a link
Reference in a new issue