@synonymdev/pubky 0.5.4 → 0.6.0-rc.2

package/README.md

@@ -1,13 +1,8 @@
 # Pubky
 
-JavaScript implementation of [Pubky](https://github.com/pubky/pubky-core) client.
+JS/WASM SDK for [Pubky](https://github.com/pubky/pubky-core).
 
-## Table of Contents
-
-- [Install](#install)
-- [Getting Started](#getting-started)
-- [API](#api)
-- [Test and Development](#test-and-development)
+Works in browsers and Node 20+.
 
 ## Install
 
@@ -15,277 +10,316 @@ JavaScript implementation of [Pubky](https://github.com/pubky/pubky-core) client
 npm install @synonymdev/pubky
 ```
 
-### Prerequisites
+> **Node**: requires Node v20+ (undici fetch, WebCrypto).
 
-For Nodejs, you need Node v20 or later.
+Module system + TS types: ESM and CommonJS both supported; TypeScript typings generated via tsify are included. Use `import { Pubky } from "@synonymdev/pubky"` (ESM) or `const { Pubky } = require("@synonymdev/pubky")` (CJS).
 
-## Getting started
+## Getting Started
 
 ```js
-import { Client, Keypair, PublicKey } from "../index.js";
+import { Pubky, PublicKey, Keypair } from "@synonymdev/pubky";
 
-// Initialize Client with Pkarr relay(s).
-let client = new Client();
+// Initiate a Pubky SDK facade wired for default mainnet Pkarr relays.
+const pubky = new Pubky(); // or: const pubky = Pubky.testnet(); for localhost testnet.
 
-// Generate a keypair
-let keypair = Keypair.random();
+// 1) Create random user keys and bind to a new Signer.
+const keypair = Keypair.random();
+const signer = pubky.signer(keypair);
 
-// Create a new account
-let homeserver = PublicKey.from(
+// 2) Sign up at a homeserver (optionally with an invite)
+const homeserver = PublicKey.from(
   "8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo"
 );
+const signupToken = "<your-invite-code-or-null>";
+const session = await signer.signup(homeserver, signupToken);
 
-await client.signup(keypair, homeserver, signup_token);
+// 3) Write a public JSON file (session-scoped storage uses cookies automatically)
+const path = "/pub/example.com/hello.json";
+await session.storage().putJson(path, { hello: "world" });
 
-const publicKey = keypair.publicKey();
+// 4) Read it publicly (no auth needed)
+const userPk = session.info().publicKey();
+const addr = `${userPk.z32()}/pub/example.com/hello.json`;
+const json = await pubky.publicStorage().getJson(addr); // -> { hello: "world" }
+```
 
-// Pubky URL
-let url = `pubky://${publicKey.z32()}/pub/example.com/arbitrary`;
+Find here [**ready-to-run examples**](https://github.com/pubky/pubky-core/tree/main/examples).
 
-// Verify that you are signed in.
-const session = await client.session(publicKey);
+## API Overview
 
-// PUT public data, by authorized client
-await client.fetch(url, {
-  method: "PUT",
-  body: JSON.stringify({ foo: "bar" }),
-  credentials: "include",
-});
+Use `new Pubky()` to quickly get any flow started:
 
-// GET public data without signup or signin
-{
-  const client = new Client();
+```js
+import { Pubky, Keypair } from "@synonymdev/pubky";
 
-  let response = await client.fetch(url);
-}
+// Mainnet (default relays)
+const pubky = new Pubky();
 
-// Delete public data, by authorized client
-await client.fetch(url, { method: "DELETE", credentials: "include " });
-```
+// Local testnet wiring (Pkarr + HTTP mapping).
+// Omit the argument for "localhost".
+const pubkyLocal = Pubky.testnet("localhost");
 
-## API
+// Signer (bind your keypair to a new Signer actor)
+const signer = pubky.signer(Keypair.random());
 
-### Client
+// Public storage (read-only)
+const publicStorage = pubky.publicStorage();
 
-#### constructor
+// PKDNS resolver (read-only)
+const pkdns = pubky.pkdns();
 
-```js
-let client = new Client();
+// Optional: raw HTTP client for advanced use
+const client = pubky.client();
 ```
 
-#### fetch
+### Client (HTTP bridge)
 
 ```js
-let response = await client.fetch(url, opts);
+import { Client } from "@synonymdev/pubky";
+
+const client = new Client(); // or: pubky.client(); instead of constructing a client manually
+
+// Works with both pubky:// and http(s)://
+const res = await client.fetch("pubky://<pubky>/pub/example.com/file.txt");
 ```
 
-Just like normal Fetch API, but it can handle `pubky://` urls and `http(s)://` urls with Pkarr domains.
+---
 
-#### signup
+### Keys
 
 ```js
-await client.signup(keypair, homeserver, signup_token);
-```
-
-- keypair: An instance of [Keypair](#keypair).
-- homeserver: An instance of [PublicKey](#publickey) representing the homeserver.
-- signup_token: A homeserver could optionally ask for a valid signup token (aka, invitation code).
+import { Keypair, PublicKey } from "@synonymdev/pubky";
 
-Returns:
+const keypair = Keypair.random();
+const pubkey = keypair.publicKey();
 
-- session: An instance of [Session](#session).
+// z-base-32 roundtrip
+const parsed = PublicKey.from(pubkey.z32());
+```
 
-#### signin
+#### Recovery file (encrypt/decrypt root secret)
 
 ```js
-let session = await client.signin(keypair);
+// Encrypt to recovery file (Uint8Array)
+const recoveryFile = keypair.createRecoveryFile("strong passphrase");
+
+// Decrypt back into a Keypair
+const restored = Keypair.fromRecoveryFile(recoveryFile, "strong passphrase");
+
+// Build a Signer from a recovered key
+const signer = pubky.signer(restored);
 ```
 
 - keypair: An instance of [Keypair](#keypair).
+- passphrase: A utf-8 string [passphrase](https://www.useapassphrase.com/).
+- Returns: A recovery file with a spec line and an encrypted secret key.
 
-Returns:
-
-- An instance of [Session](#session).
+---
 
-#### signout
+### Signer & Session
 
 ```js
-await client.signout(publicKey);
-```
+import { Pubky, PublicKey, Keypair } from "@synonymdev/pubky";
 
-- publicKey: An instance of [PublicKey](#publicKey).
+const pubky = new Pubky();
 
-#### authRequest
+const keypair = Keypair.random();
+const signer = pubky.signer(keypair);
 
-```js
-let pubkyAuthRequest = client.authRequest(relay, capabilities);
-
-let pubkyauthUrl = pubkyAuthRequest.url();
+const homeserver = PublicKey.from("8pinxxgq…");
+const session = await signer.signup(homeserver, /* invite */ null);
 
-showQr(pubkyauthUrl);
+const session2 = await signer.signin(); // fast, prefer this; publishes PKDNS in background
+const session3 = await signer.signinBlocking(); // slower but safer; waits for PKDNS publish
 
-let pubky = await pubkyAuthRequest.response();
+await session.signout(); // invalidates server session
 ```
 
-Sign in to a user's Homeserver, without access to their [Keypair](#keypair), nor even [PublicKey](#publickey),
-instead request permissions (showing the user pubkyauthUrl), and await a Session after the user consenting to that request.
+**Session details**
 
-- relay: A URL to an [HTTP relay](https://httprelay.io/features/link/) endpoint.
-- capabilities: A list of capabilities required for the app for example `/pub/pubky.app/:rw,/pub/example.com/:r`.
+```js
+const info = session.info();
+const userPk = info.publicKey(); // -> PublicKey
+const caps = info.capabilities(); // -> string[]
 
-#### sendAuthToken
+const storage = session.storage(); // -> SessionStorage (absolute paths)
+```
+
+**Approve a pubkyauth request URL**
 
 ```js
-await client.sendAuthToken(keypair, pubkyauthUrl);
+await signer.approveAuthRequest("pubkyauth:///?caps=...&secret=...&relay=...");
 ```
 
-Consenting to authentication or authorization according to the required capabilities in the `pubkyauthUrl` , and sign and send an auth token to the requester.
+---
 
-- keypair: An instance of [KeyPair](#keypair)
-- pubkyauthUrl: A string `pubkyauth://` url
+### AuthFlow (pubkyauth)
 
-#### session {#session-method}
+End-to-end auth (3rd-party app asks a user to approve via QR/deeplink, E.g. Pubky Ring).
 
 ```js
-let session = await client.session(publicKey);
-```
+import { Pubky } from "@synonymdev/pubky";
+const pubky = new Pubky();
 
-- publicKey: An instance of [PublicKey](#publickey).
-- Returns: A [Session](#session) object if signed in, or undefined if not.
+// Comma-separated capabilities string
+const caps = "/pub/my.app/:rw,/pub/another.app/folder/:w";
 
-### list
+// Optional relay; defaults to Synonym-hosted relay if omitted
+const relay = "https://httprelay.pubky.app/link/"; // optional (defaults to this)
 
-```js
-let response = await client.list(url, cursor, reverse, limit);
-```
+// Start the auth polling
+const flow = pubky.startAuthFlow(caps, relay);
+
+renderQr(flow.authorizationUrl()); // show to user
 
-- url: A string representing the Pubky URL. The path in that url is the prefix that you want to list files within.
-- cursor: Usually the last URL from previous calls. List urls after/before (depending on `reverse`) the cursor.
-- reverse: Whether or not return urls in reverse order.
-- limit: Number of urls to return.
-- Returns: A list of URLs of the files in the `url` you passed.
+// Blocks until the signer approves; returns a ready Session
+const session = await flow.awaitApproval();
+```
 
-### Keypair
+#### Http Relay & reliability
 
-#### random
+- If you don’t specify a relay, `PubkyAuthFlow` defaults to a Synonym-hosted relay. If that relay is down, logins won’t complete.
+- For production and larger apps, run **your own http relay** (MIT, Docker): [https://httprelay.io](https://httprelay.io).
+  The channel is derived as `base64url(hash(secret))`; the token is end-to-end encrypted with the `secret` and cannot be decrypted by the relay.
 
-```js
-let keypair = Keypair.random();
-```
+---
 
-- Returns: A new random Keypair.
+### Storage
 
-#### fromSecretKey
+#### PublicStorage (read-only)
 
 ```js
-let keypair = Keypair.fromSecretKey(secretKey);
-```
+const pub = pubky.publicStorage();
 
-- secretKey: A 32 bytes Uint8array.
-- Returns: A new Keypair.
+// Reads
+await pub.getJson(`${userPk.z32()}/pub/example.com/data.json`);
+await pub.getText(`${userPk.z32()}/pub/example.com/readme.txt`);
+await pub.getBytes(`${userPk.z32()}/pub/example.com/icon.png`); // Uint8Array
 
-#### publicKey {#publickey-method}
+// Metadata
+await pub.exists(`${userPk.z32()}/pub/example.com/foo`); // boolean
+await pub.stats(`${userPk.z32()}/pub/example.com/foo`); // { content_length, content_type, etag, last_modified } | null
 
-```js
-let publicKey = keypair.publicKey();
+// List directory (addressed path "<pubky>/pub/.../") must include trailing `/`.
+// list(addr, cursor=null|suffix|fullUrl, reverse=false, limit?, shallow=false)
+await pub.list(`${userPk.z32()}/pub/example.com/`, null, false, 100, false);
 ```
 
-- Returns: The [PublicKey](#publickey) associated with the Keypair.
-
-#### secretKey
+#### SessionStorage (read/write; uses cookies)
 
 ```js
-let secretKey = keypair.secretKey();
-```
+const s = session.storage();
 
-- Returns: The Uint8array secret key associated with the Keypair.
+// Writes
+await s.putJson("/pub/example.com/data.json", { ok: true });
+await s.putText("/pub/example.com/note.txt", "hello");
+await s.putBytes("/pub/example.com/img.bin", new Uint8Array([1, 2, 3]));
 
-### PublicKey
+// Reads
+await s.getJson("/pub/example.com/data.json");
+await s.getText("/pub/example.com/note.txt");
+await s.getBytes("/pub/example.com/img.bin");
 
-#### from
+// Metadata
+await s.exists("/pub/example.com/data.json");
+await s.stats("/pub/example.com/data.json");
 
-```js
-let publicKey = PublicKey.from(string);
+// Listing (session-scoped absolute dir)
+await s.list("/pub/example.com/", null, false, 100, false);
+
+// Delete
+await s.delete("/pub/example.com/data.json");
 ```
 
-- string: A string representing the public key.
-- Returns: A new PublicKey instance.
+Path rules:
 
-#### z32
+- Session storage uses **absolute** paths like `"/pub/app/file.txt"`.
+- Public storage uses **addressed** form `<user>/pub/app/file.txt` (or `pubky://<user>/...`).
 
-```js
-let pubky = publicKey.z32();
-```
+**Convention:** put your app’s public data under a domain-like folder in `/pub`, e.g. `/pub/mycoolnew.app/`.
 
-Returns: The z-base-32 encoded string representation of the PublicKey.
+---
 
-### Session
+### PKDNS (Pkarr)
 
-#### pubky
+Resolve or publish `_pubky` records.
 
 ```js
-let pubky = session.pubky();
-```
+import { Pubky, PublicKey, Keypair } from "@synonymdev/pubky";
 
-Returns an instance of [PublicKey](#publickey)
+const pubky = new Pubky();
 
-#### capabilities
+// Read-only resolver
+const resolver = pubky.pkdns();
+const homeserver = await resolver.getHomeserverOf(PublicKey.from("<user-z32>")); // string | undefined
 
-```js
-let capabilities = session.capabilities();
+// With keys (signer-bound)
+const signer = pubky.signer(Keypair.random());
+
+// Republish if missing or stale (reuses current host unless overridden)
+await signer.pkdns().publishHomeserverIfStale();
+// Or force an override now:
+await signer.pkdns().publishHomeserverForce(/* optional override homeserver*/);
 ```
 
-Returns an array of capabilities, for example `["/pub/pubky.app/:rw"]`
+---
 
-### Helper functions
+## Errors
 
-#### createRecoveryFile
+All async methods throw a structured `PubkyJsError`:
 
-```js
-let recoveryFile = createRecoveryFile(keypair, passphrase);
+```ts
+type PubkyJsError = {
+  name:
+    | "RequestError" // network/server/validation/JSON
+    | "InvalidInput"
+    | "AuthenticationError"
+    | "PkarrError"
+    | "InternalError";
+  message: string;
+  statusCode?: number; // present for HTTP server errors (4xx/5xx)
+};
 ```
 
-- keypair: An instance of [Keypair](#keypair).
-- passphrase: A utf-8 string [passphrase](https://www.useapassphrase.com/).
-- Returns: A recovery file with a spec line and an encrypted secret key.
-
-#### createRecoveryFile
+Example:
 
 ```js
-let keypair = decryptRecoveryfile(recoveryFile, passphrase);
+try {
+  await publicStorage.getJson(`${pk}/pub/example.com/missing.json`);
+} catch (e) {
+  if (e.name === "RequestError" && e.statusCode === 404) {
+    // handle not found
+  }
+}
 ```
 
-- recoveryFile: An instance of Uint8Array containing the recovery file blob.
-- passphrase: A utf-8 string [passphrase](https://www.useapassphrase.com/).
-- Returns: An instance of [Keypair](#keypair).
+---
 
-## Test and Development
+## Local Test & Development
 
 For test and development, you can run a local homeserver in a test network.
 
-If you don't have Cargo Installed, start by installing it:
+1. Install Rust (for wasm builds):
 
 ```bash
 curl https://sh.rustup.rs -sSf | sh
 ```
 
-Clone the Pubky repository:
-
-```bash
-git clone https://github.com/pubky/pubky
-cd pubky-client/pkg
-```
-
-Run the local testnet server
+2. Run the local testnet:
 
 ```bash
 npm run testnet
 ```
 
-Use the logged addresses as inputs to `Client`
+3. Point the SDK at testnet:
 
 ```js
-import { Client } from "../index.js";
+import { Pubky } from "@synonymdev/pubky";
 
-const client = Client().testnet();
+const pubky = Pubky.testnet(); // defaults to localhost
+// or: const pubky = Pubky.testnet("testnet-host");  // custom host (e.g. Docker bridge)
 ```
+
+---
+
+MIT © Synonym