@synonymdev/pubky 0.6.0-rc.6 → 0.6.0

package/README.md

@@ -17,7 +17,7 @@ Module system + TS types: ESM and CommonJS both supported; TypeScript typings ge
 ## Getting Started
 
 ```js
-import { Pubky, PublicKey, Keypair } from "@synonymdev/pubky";
+import { Pubky, PublicKey, Keypair, AuthFlowKind } from "@synonymdev/pubky";
 
 // Initiate a Pubky SDK facade wired for default mainnet Pkarr relays.
 const pubky = new Pubky(); // or: const pubky = Pubky.testnet(); for localhost testnet.
@@ -28,7 +28,7 @@ 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);
@@ -38,24 +38,41 @@ 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 userPk = session.info.publicKey.toString();
+const addr = `${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`
+const authFlow = pubky.startAuthFlow("/pub/my-cool-app/:rw", AuthFlowKind::signin()); // 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).
 
+### Key formats (display vs transport)
+
+`PublicKey` has two string forms:
+
+- **Display format**: `pubky<z32>` (for logs/UI/human-facing identifiers).
+- **Transport/storage format**: raw `z32` (for hostnames, headers, query params, serde/JSON, DB storage).
+
+Use `publicKey.z32()` for transport/storage. Use `publicKey.toString()` for display.
+
+### Initialization & events
+
+The npm package bundles the WebAssembly module and **initializes it before exposing any APIs**. This avoids the common wasm-pack pitfall where events fire before the module finishes instantiating. Long-polling flows such as `authFlow.awaitApproval()` or `authFlow.tryPollOnce()` only start their relay calls after the underlying module is ready, so you won't miss approvals while the bundle is loading.
+
+### Reuse a single facade across your app
+
+Use a shared `Pubky` (e.g, via context or prop drilling) instead of constructing one per request. This avoids reinitializing transports and keeps the same client available for repeated usage.
+
 ## API Overview
 
 Use `new Pubky()` to quickly get any flow started:
 
 ```js
-import { Pubky, Keypair } from "@synonymdev/pubky";
+import { Pubky, Keypair, AuthFlowKind } from "@synonymdev/pubky";
 
 // Mainnet (default relays)
 const pubky = new Pubky();
@@ -68,7 +85,7 @@ const pubkyLocal = Pubky.testnet("localhost");
 const signer = pubky.signer(Keypair.random());
 
 // Pubky Auth flow (with capabilities)
-const authFlow = pubky.startAuthFlow("/pub/my.app/:rw");
+const authFlow = pubky.startAuthFlow("/pub/my-cool-app/:rw", AuthFlowKind::signin());
 
 // Public storage (read-only)
 const publicStorage = pubky.publicStorage;
@@ -83,12 +100,13 @@ const client = pubky.client;
 ### Client (HTTP bridge)
 
 ```js
-import { Client, resolvePubky } from "@synonymdev/pubky";
+import { Client, PublicKey, 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 userId = PublicKey.from("pubky<z32>").toString();
+const url = resolvePubky(`${userId}/pub/example.com/file.txt`);
 const res = await client.fetch(url);
 ```
 
@@ -104,6 +122,7 @@ const pubkey = keypair.publicKey;
 
 // z-base-32 roundtrip
 const parsed = PublicKey.from(pubkey.z32());
+const displayId = pubkey.toString(); // pubky<z32> (display only)
 ```
 
 #### Recovery file (encrypt/decrypt root secret)
@@ -147,12 +166,26 @@ await session.signout(); // invalidates server session
 **Session details**
 
 ```js
-const userPk = session.info.publicKey.z32(); // -> PublicKey as z32 string
+const userPk = session.info.publicKey.toString(); // -> pubky<z32> identifier
 const caps = session.info.capabilities; // -> string[] permissions and paths
 
 const storage = session.storage; // -> This User's storage API (absolute paths)
 ```
 
+**Persist a session across tab refreshes (browser)**
+
+```js
+// Save the session snapshot (no secrets inside; relies on the HTTP-only cookie).
+const snapshot = session.export();
+localStorage.setItem("pubky-session", snapshot);
+
+// Later (after a reload), rehydrate using the browser's stored cookie.
+const restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
+```
+
+> The exported string contains only public session metadata. The browser must keep the
+> HTTP-only cookie alive for the restored session to remain authenticated.
+
 **Approve a pubkyauth request URL**
 
 ```js
@@ -166,17 +199,17 @@ await signer.approveAuthRequest("pubkyauth:///?caps=...&secret=...&relay=...");
 End-to-end auth (3rd-party app asks a user to approve via QR/deeplink, E.g. Pubky Ring).
 
 ```js
-import { Pubky } from "@synonymdev/pubky";
+import { Pubky, AuthFlowKind } from "@synonymdev/pubky";
 const pubky = new Pubky();
 
 // Comma-separated capabilities string
-const caps = "/pub/my.app/:rw,/pub/another.app/folder/:w";
+const caps = "/pub/my-cool-app/:rw,/pub/another-app/folder/:w";
 
 // Optional relay; defaults to Synonym-hosted relay if omitted
 const relay = "https://httprelay.pubky.app/link/"; // optional (defaults to this)
 
 // Start the auth polling
-const flow = pubky.startAuthFlow(caps, relay);
+const flow = pubky.startAuthFlow(caps, AuthFlowKind::signin(), relay);
 
 renderQr(flow.authorizationUrl); // show to user
 
@@ -192,7 +225,7 @@ normalized string (ordering actions like `:rw`) and throws a structured error
 when the input is malformed.
 
 ```js
-import { Pubky, validateCapabilities } from "@synonymdev/pubky";
+import { Pubky, validateCapabilities, AuthFlowKind } from "@synonymdev/pubky";
 
 const pubky = new Pubky();
 
@@ -200,7 +233,7 @@ const rawCaps = formData.get("caps");
 
 try {
   const caps = validateCapabilities(rawCaps ?? "");
-  const flow = pubky.startAuthFlow(caps);
+  const flow = pubky.startAuthFlow(caps, AuthFlowKind::signin());
   renderQr(flow.authorizationUrl);
   const session = await flow.awaitApproval();
   // ...
@@ -233,19 +266,30 @@ surface precise feedback to the user.
 const pub = pubky.publicStorage;
 
 // 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
+const response = await pub.get(
+  `${userPk}/pub/example.com/data.json`
+); // -> Response (stream it)
+await pub.getJson(`${userPk}/pub/example.com/data.json`);
+await pub.getText(`${userPk}/pub/example.com/readme.txt`);
+await pub.getBytes(`${userPk}/pub/example.com/icon.png`); // Uint8Array
 
 // 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
+await pub.exists(`${userPk}/pub/example.com/foo`); // boolean
+await pub.stats(`${userPk}/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(`pubky${userPk.z32()}/pub/example.com/`, null, false, 100, false);
+await pub.list(
+  `${userPk}/pub/example.com/`,
+  null,
+  false,
+  100,
+  false
+);
 ```
 
+Use `get()` when you need the raw `Response` for streaming or custom parsing.
+
 #### SessionStorage (read/write; uses cookies)
 
 ```js
@@ -257,6 +301,7 @@ await s.putText("/pub/example.com/note.txt", "hello");
 await s.putBytes("/pub/example.com/img.bin", new Uint8Array([1, 2, 3]));
 
 // Reads
+const response = await s.get("/pub/example.com/data.json"); // -> Response (stream it)
 await s.getJson("/pub/example.com/data.json");
 await s.getText("/pub/example.com/note.txt");
 await s.getBytes("/pub/example.com/img.bin");
@@ -272,12 +317,14 @@ await s.list("/pub/example.com/", null, false, 100, false);
 await s.delete("/pub/example.com/data.json");
 ```
 
+`get()` exposes the underlying `Response`, which is handy for streaming bodies or inspecting headers before consuming content.
+
 Path rules:
 
 - 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>/...`.
 
-**Convention:** put your app’s public data under a domain-like folder in `/pub`, e.g. `/pub/mycoolnew.app/`.
+**Convention:** put your app’s public data under a domain-like folder in `/pub`, e.g. `/pub/my-new-app/`.
 
 ---
 
@@ -291,7 +338,7 @@ 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
+const homeserver = await pubky.getHomeserverOf(PublicKey.from("pubky<z32>")); // string | undefined
 
 // With keys (signer-bound)
 const signer = pubky.signer(Keypair.random());
@@ -323,7 +370,8 @@ Use `resolvePubky()` when you need to feed an addressed resource into a raw HTTP
 ```js
 import { resolvePubky } from "@synonymdev/pubky";
 
-const identifier = "pubkyoperrr8wsbpr3ue9d4qj41ge1kcc6r7fdiy6o3ugjrrhi4y77rdo/pub/pubky.app/posts/0033X02JAN0SG";
+const identifier =
+  "pubkyoperrr8wsbpr3ue9d4qj41ge1kcc6r7fdiy6o3ugjrrhi4y77rdo/pub/pubky.app/posts/0033X02JAN0SG";
 const url = resolvePubky(identifier);
 // -> "https://_pubky.operrr8wsbpr3ue9d4qj41ge1kcc6r7fdiy6o3ugjrrhi4y77rdo/pub/pubky.app/posts/0033X02JAN0SG"
 ```
@@ -332,6 +380,12 @@ Both `pubky<pk>/…` (preferred) and `pubky://<pk>/…` resolve to the same HTTP
 
 ---
 
+## WASM memory (`free()` helpers)
+
+`wasm-bindgen` generates `free()` methods on exported classes (for example `Pubky`, `AuthFlow` `PublicKey`). JavaScript's GC eventually releases the underlying Rust structs on its own, but calling `free()` lets you drop them **immediately** if you are creating many short-lived instances (e.g. in a long-running worker). It is safe to skip manual frees in typical browser or Node apps.
+
+---
+
 ## Errors
 
 All async methods throw a structured `PubkyError`:
@@ -369,6 +423,12 @@ try {
 }
 ```
 
+## Browser environment notes
+
+- Keep the Pubky client UI and the homeserver on the **same origin family** (both local or both remote). Browsers partition cookies by scheme/host, and cross-site requests (e.g., http://localhost calling https://staging…​) can silently drop or cache `SameSite`/`Secure` session cookies.
+- If you must mix environments, use a reverse proxy so the browser always talks to one consistent origin (or disable caching via devtools and clear cookies between switches).
+- When troubleshooting auth/session caching: open a fresh incognito window, clear site data for the target origin, and verify the request includes credentials.
+
 ---
 
 ## Local Test & Development