readme

2026-02-01 10:24:35 +01:00 · 2023-01-06 01:31:22 +01:00
parent 96be7385f9
commit fd09837da2
1 changed files with 48 additions and 98 deletions
--- a/README.md
+++ b/README.md
@@ -1,120 +1,70 @@
-Nostr Connect allows Nostr apps to connect with remote signing devices
------------------------
-
-Having to enter your Nostr private key on each website or random app _sucks_.
-
-## Protocol
+# 🔌 Nostr Connect SDK for TypeScript
+Nostr Connect SDK for TypeScript is a library that allows you to easily integrate Nostr Connect into your web application.


-### `TL;DR`
+## 📦 Installation
+You can install the SDK using npm or yarn:

-
-**App** (*typically a web app, it generates a random ephemeral keypair*) and **Wallet** (*typically a mobile app, it holds the private key of the user that represents his Nostr account*) send to each other `kind:4` encrypted DMs, using a relay of choice. 
-
-App prompts the Wallet to do things such as fetching the public key or signing events.
-
-The `content` field must be a JSONRPC-ish **request** or **response**.
-
-
-### Messages
-
-#### Request
-
-```json
-{
-  "id": <random_string>,
-  "method": <one_of_the_methods>,
-  "params": [<anything>, <else>]
-}
+```bash 
+npm install @nostr-connect/connect
+# or with yarn
+yarn add @nostr-connect/connect
 ```

-#### Response

-```json
-{
-  "id": <request_id>,
-  "result": <anything>,
-  "error": <reason>
-}
+## 🚀 Getting started
+
+### Create an ephemeral key
+
+To use the SDK, you need to create an ephemeral key. This key is used to authenticate your user and to create a session.
+
+```typescript
+import { generatePrivateKey } from 'nostr-tools';
+
+const sk = generatePrivateKey();
 ```

-### Methods

- `connect`
-  - params [`pubkey`]
- `disconnect`
-  - params []
- `get_public_key`
-  - params []
-  - result `pubkey`
- `sign_event`
-  - params [`event`]
-  - result `signature`
+### Create a Nostr Connect instance

-#### optional
+To create a Nostr Connect instance, you need to provide the ephemeral key and the Nostr Connect URL.

- `delegate`
- `get_relays`
- `nip04_encrypt`
- `nip04_decrypt`
+```typescript
+import { Connect } from '@nostr-connect/connect';


-### Nostr Connect URI
-
-**Walle** discovers **App** by scanning a QR code or clicking on a deep link or copy-pasting an URI.
-
-The **App** generates a special URI with prefix `nostr://` and base path `connect` with the following querystring parameters
-
- `target` hexadecimal public key of the **App**
- `relay` URL of the relay of choice where the **App** is connected and the **Wallet** must send and listen for messages.
- `metadata`  metadata JSON of the **App** 
-    - `url` URL of the website requesting the connection
-    - `name` human-readable name of the **App** 
-    - `description` (optional) description of the **App**
-    - `icons` (optional) array of URLs for icons of the **App**.
-
-#### Example
-
-```sh
-nostr://conect?target=<pubkey>&relay=<relay>&metadata={"url": "example.com","name": "Example"}
+const connect = new Connect({ secretKey: sk, relay: 'wss://relay.nostr-connect.com' });
+connect.events.on('connect', ( walletPubkey:string ) => {
+  console.log('connected with wallet: ' + walletPubkey);
+});
+await connect.init();
 ```

-## Flow
+### Generate a ConnectURI and display it to the user


-## Connect
+```typescript
+const connectURI = new ConnectURI({
+  target: webPK,
+  relayURL: 'wss://nostr.vulpem.com',
+  metadata: {
+    name: 'My Website',
+    description: 'lorem ipsum dolor sit amet',
+    url: 'https://vulpem.com',
+    icons: ['https://vulpem.com/1000x860-p-500.422be1bc.png'],
+  },
+});

-1. User clicks on **"Connect"** button on a website or scan it with a QR code
-2. It will show an URI to open a "nostr connect" enabled **Wallet** 
-3. In the URI there is a pubkey of the **App** ie. `nostr://conect?target=<pubkey>&relay=<relay>&metadata=<metadata>`
-4. The **Wallet** will send a kind 4 encrypted message to ACK the `connect` request, along with his public key
-
-## Disconnect (from App)
-
-1. User clicks on **"Disconnect"** button on the **App**
-2. The **App** will send a kind 4 encrypted message to the **Wallet** with a `disconnect` request
-3. The **Wallet** will send a kind 4 encrypted message to ACK the `disconnect` request
-
-## Disconnect (from Wallet)
-
-1. User clicks on **"Disconnect"** button on the **Wallet**
-2. The **Wallet** will send a kind 4 encrypted message to the **App** with a `disconnect` request
+const uri = connectURI.toString();
+```


-## Get Public Key
+### Start making requests

-1. The **App** will send a kind 4 encrypted message to the **Wallet** with a `get_public_key` request
-3. The **Wallet** will send back a kind 4 encrypted message with the public key as a response to the `get_public_key` request
+```typescript
+// send the get_public_key message to the mobile app 
+const pubkey = await connect.getPublicKey();

-## Sign Event
-
-1. The **App** will send a kind 4 encrypted message to the **Wallet** with a `sign_event` request along with the **event** to be signed
-2. The **Wallet** will show a popup to the user to inspect the event and sign it
-3. The **Wallet** will send back a kind 4 encrypted message with the schnorr `signature` of the event as a response to the `sign_event` request
-
-## Delegate
-
-1. The **App** will send a kind 4 encrypted message with metadata to the **Wallet** with a `delegate` request along with the **conditions** query string and the **pubkey** of the **App** to be delegated.
-2. The **Wallet** will show a popup to the user to delegate the **App** to sign on his behalf
-3. The **Wallet** will send back a kind 4 encrypted message with the signed [NIP-26 delegation token](https://github.com/nostr-protocol/nips/blob/master/26.md) or reject it
-4. All others subsequent `delegate` Requests will be ACKed automatically
+// send the sign_event message to the mobile app
+const sig = await connect.signEvent(event);
+```