@synonymdev/pubky 0.6.0-rc.7 → 0.6.0

package/README.md

@@ -38,8 +38,8 @@ 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
@@ -50,10 +50,23 @@ 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:
@@ -87,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);
 ```
 
@@ -108,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)
@@ -151,7 +166,7 @@ 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)
@@ -252,20 +267,20 @@ const pub = pubky.publicStorage;
 
 // Reads
 const response = await pub.get(
-  `pubky${userPk.z32()}/pub/example.com/data.json`
+  `${userPk}/pub/example.com/data.json`
 ); // -> Response (stream it)
-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
+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/`,
+  `${userPk}/pub/example.com/`,
   null,
   false,
   100,
@@ -323,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());

package/index.cjs

@@ -471,8 +471,7 @@ class AuthFlow {
      * @returns {Promise<Session>}
      */
     awaitApproval() {
-        const ptr = this.__destroy_into_raw();
-        const ret = wasm.authflow_awaitApproval(ptr);
+        const ret = wasm.authflow_awaitApproval(this.__wbg_ptr);
         return ret;
     }
     /**
@@ -486,8 +485,7 @@ class AuthFlow {
      * @returns {Promise<AuthToken>}
      */
     awaitToken() {
-        const ptr = this.__destroy_into_raw();
-        const ret = wasm.authflow_awaitToken(ptr);
+        const ret = wasm.authflow_awaitToken(this.__wbg_ptr);
         return ret;
     }
     /**
@@ -600,7 +598,7 @@ const AuthTokenFinalization = (typeof FinalizationRegistry === 'undefined')
  * const token = await flow.awaitToken();
  *
  * // Identify the user
- * console.log(token.publicKey().z32());
+ * console.log(token.publicKey().toString());
  *
  * // Optionally forward to a server for verification:
  * await fetch("/api/verify", { method: "POST", body: token.toBytes() });
@@ -645,7 +643,7 @@ class AuthToken {
      * export async function POST(req) {
      *   const bytes = new Uint8Array(await req.arrayBuffer());
      *   const token = AuthToken.verify(bytes); // throws on failure
-     *   return new Response(token.publicKey().z32(), { status: 200 });
+     *   return new Response(token.publicKey().toString(), { status: 200 });
      * }
      * ```
      * @param {Uint8Array} bytes
@@ -678,10 +676,11 @@ class AuthToken {
     /**
      * Returns the **public key** that authenticated with this token.
      *
-     * Use `.z32()` on the returned `PublicKey` to get the string form.
+     * Use `.toString()` on the returned `PublicKey` to get the `pubky<z32>` identifier.
+     * Call `.z32()` when you specifically need the raw z-base32 value (e.g. hostnames).
      *
      * @example
-     * const who = sessionInfo.publicKey.z32();
+     * const who = token.publicKey.toString();
      * @returns {PublicKey}
      */
     get publicKey() {
@@ -755,6 +754,26 @@ class Client {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_client_free(ptr, 0);
     }
+    /**
+     * Perform a raw fetch. Works with `http(s)://` URLs.
+     *
+     * @param {string} url
+     * @param {RequestInit} init Standard fetch options; `credentials: "include"` recommended for session I/O.
+     * @returns {Promise<Response>}
+     *
+     * @example
+     * const client = pubky.client;
+     * const res = await client.fetch(`https://_pubky.${user}/pub/app/file.txt`, { method: "PUT", body: "hi", credentials: "include" });
+     * @param {string} url
+     * @param {RequestInit | null} [init]
+     * @returns {Promise<Response>}
+     */
+    fetch(url, init) {
+        const ptr0 = passStringToWasm0(url, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.client_fetch(this.__wbg_ptr, ptr0, len0, isLikeNone(init) ? 0 : addToExternrefTable0(init));
+        return ret;
+    }
     /**
      * Create a Pubky HTTP client.
      *
@@ -814,26 +833,6 @@ class Client {
         }
         return Client.__wrap(ret[0]);
     }
-    /**
-     * Perform a raw fetch. Works with `http(s)://` URLs.
-     *
-     * @param {string} url
-     * @param {RequestInit} init Standard fetch options; `credentials: "include"` recommended for session I/O.
-     * @returns {Promise<Response>}
-     *
-     * @example
-     * const client = pubky.client;
-     * const res = await client.fetch(`https://_pubky.${user}/pub/app/file.txt`, { method: "PUT", body: "hi", credentials: "include" });
-     * @param {string} url
-     * @param {RequestInit | null} [init]
-     * @returns {Promise<Response>}
-     */
-    fetch(url, init) {
-        const ptr0 = passStringToWasm0(url, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.client_fetch(this.__wbg_ptr, ptr0, len0, isLikeNone(init) ? 0 : addToExternrefTable0(init));
-        return ret;
-    }
 }
 if (Symbol.dispose) Client.prototype[Symbol.dispose] = Client.prototype.free;
 
@@ -1016,34 +1015,36 @@ class Keypair {
         return Keypair.__wrap(ret);
     }
     /**
-     * Generate a [Keypair] from a secret key.
-     * @param {Uint8Array} secret_key
+     * Generate a [Keypair] from a 32-byte secret.
+     * @param {Uint8Array} secret
      * @returns {Keypair}
      */
-    static fromSecretKey(secret_key) {
-        const ptr0 = passArray8ToWasm0(secret_key, wasm.__wbindgen_malloc);
+    static fromSecret(secret) {
+        const ptr0 = passArray8ToWasm0(secret, wasm.__wbindgen_malloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.keypair_fromSecretKey(ptr0, len0);
+        const ret = wasm.keypair_fromSecret(ptr0, len0);
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
         return Keypair.__wrap(ret[0]);
     }
     /**
-     * Returns the secret key of this keypair.
+     * Returns the secret of this keypair.
      * @returns {Uint8Array}
      */
-    secretKey() {
-        const ret = wasm.keypair_secretKey(this.__wbg_ptr);
+    secret() {
+        const ret = wasm.keypair_secret(this.__wbg_ptr);
         return ret;
     }
     /**
      * Returns the [PublicKey] of this keypair.
      *
-     * Use `.z32()` on the returned `PublicKey` to get the string form.
+     * Use `.toString()` on the returned `PublicKey` to get the string form
+     * or `.z32()` to get the z32 string form without prefix.
+     * Transport/storage (query params, headers, persistence) should use `.z32()`.
      *
      * @example
-     * const who = keypair.publicKey.z32();
+     * const who = keypair.publicKey.toString();
      * @returns {PublicKey}
      */
     get publicKey() {
@@ -1231,6 +1232,10 @@ class Pubky {
     /**
      * Create a Pubky facade wired for **mainnet** defaults (public relays).
      *
+     * Prefer to instantiate only once and use trough your application a single shared `Pubky`
+     * instead of constructing one per request. This avoids reinitializing transports and keeps
+     * the same client available for repeated usage.
+     *
      * @returns {Pubky}
      * A new facade instance. Use this to create signers, start auth flows, etc.
      *
@@ -1355,12 +1360,12 @@ class Pubky {
      * Public, unauthenticated storage API.
      *
      * Use for **read-only** public access via addressed paths:
-     * `"<user-z32>/pub/…"`.
+     * `"pubky<user>/pub/…"`.
      *
      * @returns {PublicStorage}
      *
      * @example
-     * const text = await pubky.publicStorage.getText(`${userPk.z32()}/pub/example.com/hello.txt`);
+     * const text = await pubky.publicStorage.getText(`${userPk.toString()}/pub/example.com/hello.txt`);
      * @returns {PublicStorage}
      */
     get publicStorage() {
@@ -1373,7 +1378,7 @@ class Pubky {
      * Uses an internal read-only Pkdns actor.
      *
      * @param {PublicKey} user
-     * @returns {Promise<PublicKey|undefined>} Homeserver public key (z32) or `undefined` if not found.
+     * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
      * @param {PublicKey} user_public_key
      * @returns {Promise<PublicKey | undefined>}
      */
@@ -1389,7 +1394,7 @@ class Pubky {
      * Use this for low-level `fetch()` calls or testing with raw URLs.
      *
      * @example
-     * const r = await pubky.client.fetch(`pubky://${user}/pub/app/file.txt`, { credentials: "include" });
+     * const r = await pubky.client.fetch(`pubky://${userPk.z32()}/pub/app/file.txt`, { credentials: "include" });
      * @returns {Client}
      */
     get client() {
@@ -1471,6 +1476,23 @@ class PublicKey {
             wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Returns the identifier form with the `pubky` prefix.
+     * Use for display only; transport/storage should use `.z32()`.
+     * @returns {string}
+     */
+    toString() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.publickey_toString(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * @throws
      * @param {string} value
@@ -1494,7 +1516,7 @@ const PublicStorageFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_publicstorage_free(ptr >>> 0, 1));
 /**
- * Read-only public storage using addressed paths (`"<user-z32>/pub/...")`.
+ * Read-only public storage using addressed paths (`"pubky<user>/pub/..."`).
  */
 class PublicStorage {
 
@@ -1851,12 +1873,13 @@ class SessionInfo {
     /**
      * The user’s public key for this session.
      *
-     * Use `.z32()` on the returned `PublicKey` to get the string form.
+     * Use `.toString()` on the returned `PublicKey` to get the `pubky<z32>` identifier.
+     * Call `.z32()` when you specifically need the raw z-base32 value (e.g. hostnames).
      *
      * @returns {PublicKey}
      *
      * @example
-     * const who = sessionInfo.publicKey.z32();
+     * const who = sessionInfo.publicKey.toString();
      * @returns {PublicKey}
      */
     get publicKey() {
@@ -2642,12 +2665,12 @@ exports.__wbg_error_d8b22cf4e59a6791 = function(arg0, arg1, arg2, arg3) {
     console.error(arg0, arg1, arg2, arg3);
 };
 
-exports.__wbg_fetch_74a3e84ebd2c9a0e = function(arg0) {
+exports.__wbg_fetch_013f0d75d4254327 = function(arg0) {
     const ret = fetch(arg0);
     return ret;
 };
 
-exports.__wbg_fetch_cd778f2325984326 = function(arg0) {
+exports.__wbg_fetch_74a3e84ebd2c9a0e = function(arg0) {
     const ret = fetch(arg0);
     return ret;
 };