@synonymdev/pubky 0.6.0-rc.2 → 0.6.0-rc.6

package/README.md

@@ -28,19 +28,24 @@ const signer = pubky.signer(keypair);
 
 // 2) Sign up at a homeserver (optionally with an invite)
 const homeserver = PublicKey.from(
-  "8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo"
+  "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" });
+await session.storage.putJson(path, { hello: "world" });
 
 // 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" }
+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();
 ```
 
 Find here [**ready-to-run examples**](https://github.com/pubky/pubky-core/tree/main/examples).
@@ -62,25 +67,29 @@ const pubkyLocal = Pubky.testnet("localhost");
 // Signer (bind your keypair to a new Signer actor)
 const signer = pubky.signer(Keypair.random());
 
+// Pubky Auth flow (with capabilities)
+const authFlow = pubky.startAuthFlow("/pub/my.app/:rw");
+
 // Public storage (read-only)
-const publicStorage = pubky.publicStorage();
+const publicStorage = pubky.publicStorage;
 
-// PKDNS resolver (read-only)
-const pkdns = pubky.pkdns();
+// Pkdns resolver
+const pkdns = pubky.getHomeserverOf(publicKey);
 
 // Optional: raw HTTP client for advanced use
-const client = pubky.client();
+const client = pubky.client;
 ```
 
 ### Client (HTTP bridge)
 
 ```js
-import { Client } from "@synonymdev/pubky";
+import { Client, resolvePubky } from "@synonymdev/pubky";
 
-const client = new Client(); // or: pubky.client(); instead of constructing a client manually
+const client = new Client(); // or: pubky.client.fetch(); 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");
+// 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);
 ```
 
 ---
@@ -91,7 +100,7 @@ const res = await client.fetch("pubky://<pubky>/pub/example.com/file.txt");
 import { Keypair, PublicKey } from "@synonymdev/pubky";
 
 const keypair = Keypair.random();
-const pubkey = keypair.publicKey();
+const pubkey = keypair.publicKey;
 
 // z-base-32 roundtrip
 const parsed = PublicKey.from(pubkey.z32());
@@ -138,11 +147,10 @@ await session.signout(); // invalidates server session
 **Session details**
 
 ```js
-const info = session.info();
-const userPk = info.publicKey(); // -> PublicKey
-const caps = info.capabilities(); // -> string[]
+const userPk = session.info.publicKey.z32(); // -> PublicKey as z32 string
+const caps = session.info.capabilities; // -> string[] permissions and paths
 
-const storage = session.storage(); // -> SessionStorage (absolute paths)
+const storage = session.storage; // -> This User's storage API (absolute paths)
 ```
 
 **Approve a pubkyauth request URL**
@@ -170,12 +178,45 @@ const relay = "https://httprelay.pubky.app/link/"; // optional (defaults to this
 // Start the auth polling
 const flow = pubky.startAuthFlow(caps, relay);
 
-renderQr(flow.authorizationUrl()); // show to user
+renderQr(flow.authorizationUrl); // show to user
 
 // Blocks until the signer approves; returns a ready Session
 const session = await flow.awaitApproval();
 ```
 
+#### Validate and normalize capabilities
+
+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
+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;
+}
+```
+
+On invalid input, `validateCapabilities` throws a `PubkyError` with
+`{ name: "InvalidInput", message: "Invalid capability entries: …" }`, so you can
+surface precise feedback to the user.
+
 #### Http Relay & reliability
 
 - If you don’t specify a relay, `PubkyAuthFlow` defaults to a Synonym-hosted relay. If that relay is down, logins won’t complete.
@@ -189,26 +230,26 @@ const session = await flow.awaitApproval();
 #### PublicStorage (read-only)
 
 ```js
-const pub = pubky.publicStorage();
+const pub = pubky.publicStorage;
 
 // 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
+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
 
 // 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
+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
 
 // 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);
+await pub.list(`pubky${userPk.z32()}/pub/example.com/`, null, false, 100, false);
 ```
 
 #### SessionStorage (read/write; uses cookies)
 
 ```js
-const s = session.storage();
+const s = session.storage;
 
 // Writes
 await s.putJson("/pub/example.com/data.json", { ok: true });
@@ -234,7 +275,7 @@ await s.delete("/pub/example.com/data.json");
 Path rules:
 
 - Session storage uses **absolute** paths like `"/pub/app/file.txt"`.
-- Public storage uses **addressed** form `<user>/pub/app/file.txt` (or `pubky://<user>/...`).
+- Public storage uses **addressed** form `pubky<user>/pub/app/file.txt` (preferred) or `pubky://<user>/...`.
 
 **Convention:** put your app’s public data under a domain-like folder in `/pub`, e.g. `/pub/mycoolnew.app/`.
 
@@ -250,26 +291,53 @@ import { Pubky, PublicKey, Keypair } from "@synonymdev/pubky";
 const pubky = new Pubky();
 
 // Read-only resolver
-const resolver = pubky.pkdns();
-const homeserver = await resolver.getHomeserverOf(PublicKey.from("<user-z32>")); // string | undefined
+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();
+await signer.pkdns.publishHomeserverIfStale();
 // Or force an override now:
-await signer.pkdns().publishHomeserverForce(/* optional override homeserver*/);
+await signer.pkdns.publishHomeserverForce(/* optional override homeserver*/);
+// Resolve your own homeserver:
+await signer.pkdns.getHomeserver();
 ```
 
+## Logging
+
+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
+import { setLogLevel } from "@synonymdev/pubky";
+
+setLogLevel("debug"); // "error" | "warn" | "info" | "debug" | "trace"
+```
+
+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.
+
+#### Resolve `pubky` identifiers into transport URLs
+
+Use `resolvePubky()` when you need to feed an addressed resource into a raw HTTP client:
+
+```js
+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"
+```
+
+Both `pubky<pk>/…` (preferred) and `pubky://<pk>/…` resolve to the same HTTPS endpoint.
+
 ---
 
 ## Errors
 
-All async methods throw a structured `PubkyJsError`:
+All async methods throw a structured `PubkyError`:
 
 ```ts
-type PubkyJsError = {
+interface PubkyError extends Error {
   name:
     | "RequestError" // network/server/validation/JSON
     | "InvalidInput"
@@ -277,8 +345,8 @@ type PubkyJsError = {
     | "PkarrError"
     | "InternalError";
   message: string;
-  statusCode?: number; // present for HTTP server errors (4xx/5xx)
-};
+  data?: unknown; // structured context when available (e.g. { statusCode: number })
+}
 ```
 
 Example:
@@ -287,7 +355,15 @@ Example:
 try {
   await publicStorage.getJson(`${pk}/pub/example.com/missing.json`);
 } catch (e) {
-  if (e.name === "RequestError" && e.statusCode === 404) {
+  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
   }
 }
@@ -299,16 +375,17 @@ try {
 
 For test and development, you can run a local homeserver in a test network.
 
-1. Install Rust (for wasm builds):
+1. Install Rust (for wasm and testnet builds):
 
 ```bash
 curl https://sh.rustup.rs -sSf | sh
 ```
 
-2. Run the local testnet:
+2. Install and run the local testnet:
 
 ```bash
-npm run testnet
+cargo install pubky-testnet
+pubky-testnet
 ```
 
 3. Point the SDK at testnet: