@synonymdev/pubky 0.5.4 → 0.6.0-rc.6

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,393 @@ 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(
-  "8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo"
+// 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);
+
+// 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" });
+
+// 4) Read it publicly (no auth needed)
+const userPk = session.info.publicKey.z32();
+const addr = `pubky${userPk}/pub/example.com/hello.json`;
+const json = await pubky.publicStorage.getJson(addr); // -> { hello: "world" }
+
+// 5) Authenticate on a 3rd-party app
+const authFlow = pubky.startAuthFlow("/pub/my.app/:rw"); // require permissions to read and write into `my.app`
+renderQr(authFlow.authorizationUrl); // show to user
+const session = await authFlow.awaitApproval();
+```
 
-await client.signup(keypair, homeserver, signup_token);
+Find here [**ready-to-run examples**](https://github.com/pubky/pubky-core/tree/main/examples).
 
-const publicKey = keypair.publicKey();
+## API Overview
 
-// Pubky URL
-let url = `pubky://${publicKey.z32()}/pub/example.com/arbitrary`;
+Use `new Pubky()` to quickly get any flow started:
 
-// Verify that you are signed in.
-const session = await client.session(publicKey);
+```js
+import { Pubky, Keypair } from "@synonymdev/pubky";
 
-// PUT public data, by authorized client
-await client.fetch(url, {
-  method: "PUT",
-  body: JSON.stringify({ foo: "bar" }),
-  credentials: "include",
-});
+// Mainnet (default relays)
+const pubky = new Pubky();
 
-// GET public data without signup or signin
-{
-  const client = new Client();
+// Local testnet wiring (Pkarr + HTTP mapping).
+// Omit the argument for "localhost".
+const pubkyLocal = Pubky.testnet("localhost");
 
-  let response = await client.fetch(url);
-}
+// Signer (bind your keypair to a new Signer actor)
+const signer = pubky.signer(Keypair.random());
 
-// Delete public data, by authorized client
-await client.fetch(url, { method: "DELETE", credentials: "include " });
-```
+// Pubky Auth flow (with capabilities)
+const authFlow = pubky.startAuthFlow("/pub/my.app/:rw");
+
+// Public storage (read-only)
+const publicStorage = pubky.publicStorage;
 
-## API
+// Pkdns resolver
+const pkdns = pubky.getHomeserverOf(publicKey);
 
-### Client
+// Optional: raw HTTP client for advanced use
+const client = pubky.client;
+```
 
-#### constructor
+### Client (HTTP bridge)
 
 ```js
-let client = new Client();
+import { Client, resolvePubky } from "@synonymdev/pubky";
+
+const client = new Client(); // or: pubky.client.fetch(); instead of constructing a client manually
+
+// Convert the identifier into a transport URL before fetching.
+const url = resolvePubky("pubky<pubky>/pub/example.com/file.txt");
+const res = await client.fetch(url);
 ```
 
-#### fetch
+---
+
+### Keys
 
 ```js
-let response = await client.fetch(url, opts);
-```
+import { Keypair, PublicKey } from "@synonymdev/pubky";
+
+const keypair = Keypair.random();
+const pubkey = keypair.publicKey;
 
-Just like normal Fetch API, but it can handle `pubky://` urls and `http(s)://` urls with Pkarr domains.
+// z-base-32 roundtrip
+const parsed = PublicKey.from(pubkey.z32());
+```
 
-#### signup
+#### Recovery file (encrypt/decrypt root secret)
 
 ```js
-await client.signup(keypair, homeserver, signup_token);
+// 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).
-- homeserver: An instance of [PublicKey](#publickey) representing the homeserver.
-- signup_token: A homeserver could optionally ask for a valid signup token (aka, invitation code).
-
-Returns:
+- passphrase: A utf-8 string [passphrase](https://www.useapassphrase.com/).
+- Returns: A recovery file with a spec line and an encrypted secret key.
 
-- session: An instance of [Session](#session).
+---
 
-#### signin
+### Signer & Session
 
 ```js
-let session = await client.signin(keypair);
-```
+import { Pubky, PublicKey, Keypair } from "@synonymdev/pubky";
 
-- keypair: An instance of [Keypair](#keypair).
+const pubky = new Pubky();
 
-Returns:
+const keypair = Keypair.random();
+const signer = pubky.signer(keypair);
 
-- An instance of [Session](#session).
+const homeserver = PublicKey.from("8pinxxgq…");
+const session = await signer.signup(homeserver, /* invite */ null);
 
-#### signout
+const session2 = await signer.signin(); // fast, prefer this; publishes PKDNS in background
+const session3 = await signer.signinBlocking(); // slower but safer; waits for PKDNS publish
 
-```js
-await client.signout(publicKey);
+await session.signout(); // invalidates server session
 ```
 
-- publicKey: An instance of [PublicKey](#publicKey).
-
-#### authRequest
+**Session details**
 
 ```js
-let pubkyAuthRequest = client.authRequest(relay, capabilities);
+const userPk = session.info.publicKey.z32(); // -> PublicKey as z32 string
+const caps = session.info.capabilities; // -> string[] permissions and paths
 
-let pubkyauthUrl = pubkyAuthRequest.url();
+const storage = session.storage; // -> This User's storage API (absolute paths)
+```
 
-showQr(pubkyauthUrl);
+**Approve a pubkyauth request URL**
 
-let pubky = await pubkyAuthRequest.response();
+```js
+await signer.approveAuthRequest("pubkyauth:///?caps=...&secret=...&relay=...");
 ```
 
-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.
+---
 
-- 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`.
+### AuthFlow (pubkyauth)
 
-#### sendAuthToken
+End-to-end auth (3rd-party app asks a user to approve via QR/deeplink, E.g. Pubky Ring).
 
 ```js
-await client.sendAuthToken(keypair, pubkyauthUrl);
-```
+import { Pubky } from "@synonymdev/pubky";
+const pubky = new Pubky();
 
-Consenting to authentication or authorization according to the required capabilities in the `pubkyauthUrl` , and sign and send an auth token to the requester.
+// Comma-separated capabilities string
+const caps = "/pub/my.app/:rw,/pub/another.app/folder/:w";
 
-- keypair: An instance of [KeyPair](#keypair)
-- pubkyauthUrl: A string `pubkyauth://` url
+// Optional relay; defaults to Synonym-hosted relay if omitted
+const relay = "https://httprelay.pubky.app/link/"; // optional (defaults to this)
 
-#### session {#session-method}
+// Start the auth polling
+const flow = pubky.startAuthFlow(caps, relay);
 
-```js
-let session = await client.session(publicKey);
+renderQr(flow.authorizationUrl); // show to user
+
+// Blocks until the signer approves; returns a ready Session
+const session = await flow.awaitApproval();
 ```
 
-- publicKey: An instance of [PublicKey](#publickey).
-- Returns: A [Session](#session) object if signed in, or undefined if not.
+#### Validate and normalize capabilities
 
-### list
+If you accept capability strings from user input (forms, CLI arguments, etc.),
+use `validateCapabilities` before calling `startAuthFlow`. The helper returns a
+normalized string (ordering actions like `:rw`) and throws a structured error
+when the input is malformed.
 
 ```js
-let response = await client.list(url, cursor, reverse, limit);
+import { Pubky, validateCapabilities } from "@synonymdev/pubky";
+
+const pubky = new Pubky();
+
+const rawCaps = formData.get("caps");
+
+try {
+  const caps = validateCapabilities(rawCaps ?? "");
+  const flow = pubky.startAuthFlow(caps);
+  renderQr(flow.authorizationUrl);
+  const session = await flow.awaitApproval();
+  // ...
+} catch (error) {
+  if (error.name === "InvalidInput") {
+    surfaceValidationError(error.message);
+    return;
+  }
+  throw error;
+}
 ```
 
-- 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.
+On invalid input, `validateCapabilities` throws a `PubkyError` with
+`{ name: "InvalidInput", message: "Invalid capability entries: …" }`, so you can
+surface precise feedback to the user.
 
-### 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(`pubky${userPk.z32()}/pub/example.com/data.json`);
+await pub.getText(`pubky${userPk.z32()}/pub/example.com/readme.txt`);
+await pub.getBytes(`pubky${userPk.z32()}/pub/example.com/icon.png`); // Uint8Array
 
-#### publicKey {#publickey-method}
+// Metadata
+await pub.exists(`pubky${userPk.z32()}/pub/example.com/foo`); // boolean
+await pub.stats(`pubky${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(`pubky${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 `pubky<user>/pub/app/file.txt` (preferred) 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";
+
+const pubky = new Pubky();
+
+// Read-only resolver
+const homeserver = await pubky.getHomeserverOf(PublicKey.from("<user-z32>")); // string | undefined
+
+// 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*/);
+// Resolve your own homeserver:
+await signer.pkdns.getHomeserver();
 ```
 
-Returns an instance of [PublicKey](#publickey)
+## Logging
 
-#### capabilities
+The SDK ships with a WASM logger that bridges Rust `log` output into the browser or Node console. Call `setLogLevel` **once at application start**, before constructing `Pubky` or other SDK actors, to choose how verbose the logs should be.
 
 ```js
-let capabilities = session.capabilities();
+import { setLogLevel } from "@synonymdev/pubky";
+
+setLogLevel("debug"); // "error" | "warn" | "info" | "debug" | "trace"
 ```
 
-Returns an array of capabilities, for example `["/pub/pubky.app/:rw"]`
+If the logger is already initialized, calling `setLogLevel` again will throw. Pick the most verbose level (`"debug"` or `"trace"`) while developing to see pkarr resolution, network requests and storage operations in the console.
 
-### Helper functions
+#### Resolve `pubky` identifiers into transport URLs
 
-#### createRecoveryFile
+Use `resolvePubky()` when you need to feed an addressed resource into a raw HTTP client:
 
 ```js
-let recoveryFile = createRecoveryFile(keypair, passphrase);
+import { resolvePubky } from "@synonymdev/pubky";
+
+const identifier = "pubkyoperrr8wsbpr3ue9d4qj41ge1kcc6r7fdiy6o3ugjrrhi4y77rdo/pub/pubky.app/posts/0033X02JAN0SG";
+const url = resolvePubky(identifier);
+// -> "https://_pubky.operrr8wsbpr3ue9d4qj41ge1kcc6r7fdiy6o3ugjrrhi4y77rdo/pub/pubky.app/posts/0033X02JAN0SG"
 ```
 
-- 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.
+Both `pubky<pk>/…` (preferred) and `pubky://<pk>/…` resolve to the same HTTPS endpoint.
+
+---
+
+## Errors
+
+All async methods throw a structured `PubkyError`:
 
-#### createRecoveryFile
+```ts
+interface PubkyError extends Error {
+  name:
+    | "RequestError" // network/server/validation/JSON
+    | "InvalidInput"
+    | "AuthenticationError"
+    | "PkarrError"
+    | "InternalError";
+  message: string;
+  data?: unknown; // structured context when available (e.g. { statusCode: number })
+}
+```
+
+Example:
 
 ```js
-let keypair = decryptRecoveryfile(recoveryFile, passphrase);
+try {
+  await publicStorage.getJson(`${pk}/pub/example.com/missing.json`);
+} catch (e) {
+  const error = e as PubkyError;
+  if (
+    error.name === "RequestError" &&
+    typeof error.data === "object" &&
+    error.data !== null &&
+    "statusCode" in error.data &&
+    typeof (error.data as { statusCode?: number }).statusCode === "number" &&
+    (error.data as { statusCode?: number }).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 and testnet builds):
 
 ```bash
 curl https://sh.rustup.rs -sSf | sh
 ```
 
-Clone the Pubky repository:
+2. Install and run the local testnet:
 
 ```bash
-git clone https://github.com/pubky/pubky
-cd pubky-client/pkg
+cargo install pubky-testnet
+pubky-testnet
 ```
 
-Run the local testnet server
-
-```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