@synonymdev/pubky 0.6.0-rc.7 → 0.6.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Pubky client",
-  "version": "0.6.0-rc.7",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,8 +13,8 @@
     "build:test": "tsc --project tsconfig.json && mkdir -p dist && cp index.js dist/index.js",
     "test": "npm run test-nodejs && npm run test-browser",
     "test-nodejs": "npm run build:test && node --require ./node-header.cjs node_modules/tape/bin/tape dist/tests/*.js -cov",
-    "test-browser": "npm run build:test && browserify dist/tests/*.js -p esmify | npx tape-run",
-    "test-browser:ci": "npm run build:test && browserify dist/tests/*.js -p esmify | tape-run --browser electron --electron-arg=--no-sandbox --electron-arg=--disable-gpu",
+    "test-browser": "npm run build:test && browserify dist/tests/setup.js dist/tests/*.js -p esmify | npx tape-run",
+    "test-browser:ci": "npm run build:test && browserify dist/tests/setup.js dist/tests/*.js -p esmify | tape-run --browser electron --electron-arg=--no-sandbox --electron-arg=--disable-gpu",
     "build": "cargo run --bin bundle_npm",
     "prepublishOnly": "npm run build"
   },

package/pubky.d.ts

@@ -53,33 +53,6 @@ type Level = "error" | "warn" | "info" | "debug" | "trace";
 type ReadableStreamType = "bytes";
 export type Path = `/pub/${string}`;
 
-export type Address = `pubky${string}/pub/${string}` | `pubky://${string}/pub/${string}`;
-
-/**
- * Pkarr Config
- */
-export interface PkarrConfig {
-    /**
-     * The list of relays to access the DHT with.
-     */
-    relays?: string[];
-    /**
-     * The timeout for DHT requests in milliseconds.
-     * Default is 2000ms.
-     */
-    requestTimeout?: number;
-}
-
-/**
- * Pubky Client Config
- */
-export interface PubkyClientConfig {
-    /**
-     * Configuration on how to access pkarr packets on the mainline DHT.
-     */
-    pkarr?: PkarrConfig;
-}
-
 export type CapabilityAction = "r" | "w" | "rw";
 export type CapabilityScope = `/${string}`;
 export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
@@ -162,6 +135,33 @@ export interface PubkyError extends Error {
   data?: unknown;
 }
 
+export type Address = `pubky${string}/pub/${string}` | `pubky://${string}/pub/${string}`;
+
+/**
+ * Pkarr Config
+ */
+export interface PkarrConfig {
+    /**
+     * The list of relays to access the DHT with.
+     */
+    relays?: string[];
+    /**
+     * The timeout for DHT requests in milliseconds.
+     * Default is 2000ms.
+     */
+    requestTimeout?: number;
+}
+
+/**
+ * Pubky Client Config
+ */
+export interface PubkyClientConfig {
+    /**
+     * Configuration on how to access pkarr packets on the mainline DHT.
+     */
+    pkarr?: PkarrConfig;
+}
+
 /**
  * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
  *
@@ -327,7 +327,7 @@ export class AuthFlowKind {
  * 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() });
@@ -355,7 +355,7 @@ export 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 });
    * }
    * ```
    */
@@ -383,10 +383,11 @@ export 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();
    */
   readonly publicKey: PublicKey;
   /**
@@ -410,6 +411,18 @@ export class AuthToken {
 export class Client {
   free(): void;
   [Symbol.dispose](): void;
+  /**
+   * 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" });
+   */
+  fetch(url: string, init?: RequestInit | null): Promise<Response>;
   /**
    * Create a Pubky HTTP client.
    *
@@ -450,18 +463,6 @@ export class Client {
    * const client = Client.testnet("docker0");  // custom host
    */
   static testnet(host?: string | null): Client;
-  /**
-   * 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" });
-   */
-  fetch(url: string, init?: RequestInit | null): Promise<Response>;
 }
 export class IntoUnderlyingByteSource {
   private constructor();
@@ -497,13 +498,13 @@ export class Keypair {
    */
   static random(): Keypair;
   /**
-   * Generate a [Keypair] from a secret key.
+   * Generate a [Keypair] from a 32-byte secret.
    */
-  static fromSecretKey(secret_key: Uint8Array): Keypair;
+  static fromSecret(secret: Uint8Array): Keypair;
   /**
-   * Returns the secret key of this keypair.
+   * Returns the secret of this keypair.
    */
-  secretKey(): Uint8Array;
+  secret(): Uint8Array;
   /**
    * Create a recovery file for this keypair (encrypted with the given passphrase).
    */
@@ -515,10 +516,12 @@ export class Keypair {
   /**
    * 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();
    */
   readonly publicKey: PublicKey;
 }
@@ -577,6 +580,10 @@ export 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.
    *
@@ -657,7 +664,7 @@ export 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.
    */
   getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>;
   /**
@@ -678,12 +685,12 @@ export 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`);
    */
   readonly publicStorage: PublicStorage;
   /**
@@ -693,7 +700,7 @@ export 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" });
    */
   readonly client: Client;
 }
@@ -709,13 +716,18 @@ export class PublicKey {
    * Returns the z-base32 encoding of this public key
    */
   z32(): string;
+  /**
+   * Returns the identifier form with the `pubky` prefix.
+   * Use for display only; transport/storage should use `.z32()`.
+   */
+  toString(): string;
   /**
    * @throws
    */
   static from(value: string): PublicKey;
 }
 /**
- * Read-only public storage using addressed paths (`"<user-z32>/pub/...")`.
+ * Read-only public storage using addressed paths (`"pubky<user>/pub/..."`).
  */
 export class PublicStorage {
   free(): void;
@@ -849,12 +861,13 @@ export 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();
    */
   readonly publicKey: PublicKey;
   /**