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

package/pubky.d.ts

@@ -3,13 +3,13 @@
 /**
  * Set the global logging verbosity for the WASM Pubky SDK. Routes Rust `log` output to the browser console.
  *
- * Accepted values (case-insensitive): "error" | "warn" | "info" | "debug" | "trace".
+ * Accepted values (case-sensitive): "error" | "warn" | "info" | "debug" | "trace".
  * Effects:
  * - Initializes the logger once; subsequent calls may throw if the logger is already set.
  * - Emits a single info log: `Log level set to: <level>`.
  * - Messages at or above `level` are forwarded to the appropriate `console.*` method.
  *
- * @param {string} level
+ * @param {Level} level
  *        Minimum log level to enable. One of: "error" | "warn" | "info" | "debug" | "trace".
  *
  * @returns {void}
@@ -21,7 +21,14 @@
  * Usage:
  *   Call once at application startup, before invoking other SDK APIs.
  */
-export function setLogLevel(level: string): void;
+export function setLogLevel(level: Level): void;
+/**
+ * Resolve a `pubky://` or `pubky<pk>/…` identifier into the homeserver transport URL.
+ *
+ * @param {string} identifier Either `pubky<pk>/...` (preferred) or `pubky://<pk>/...`.
+ * @returns {string} HTTPS URL in the form `https://_pubky.<pk>/...`.
+ */
+export function resolvePubky(identifier: string): string;
 /**
  * Validate and normalize a capabilities string.
  *
@@ -30,12 +37,64 @@ export function setLogLevel(level: string): void;
  *
  * @param {string} input
  * @returns {string} Normalized string (same shape as input).
- * @throws {PubkyJsError} `{ name: "InvalidInput" }` with a helpful message.
+ * @throws {PubkyError} `{ name: "InvalidInput" }` with a helpful message.
+ * The error's `data` field is `{ invalidEntries: string[] }` listing malformed tokens.
  */
 export function validateCapabilities(input: string): string;
+/**
+ * An enum representing the available verbosity levels of the logger.
+ */
+type Level = "error" | "warn" | "info" | "debug" | "trace";
+/**
+ * The `ReadableStreamType` enum.
+ *
+ * *This API requires the following crate features to be activated: `ReadableStreamType`*
+ */
+type ReadableStreamType = "bytes";
+/**
+ * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
+ *
+ * @typedef {Object} ResourceStats
+ * @property {number=} contentLength  Size in bytes.
+ * @property {string=} contentType    Media type (e.g. \"application/json; charset=utf-8\").
+ * @property {number=} lastModifiedMs Unix epoch milliseconds.
+ * @property {string=} etag           Opaque server ETag for the current version.
+ *
+ * @example
+ * const stats = await pubky.publicStorage.stats(`${user}/pub/app/file.json`);
+ * if (stats) {
+ *   console.log(stats.contentLength, stats.contentType, stats.lastModifiedMs);
+ * }
+ *
+ * Notes:
+ * - `contentLength` equals `getBytes(...).length`.
+ * - `etag` may be absent and is opaque; compare values to detect updates.
+ * - `lastModifiedMs` increases when the resource is updated.
+ */
+export interface ResourceStats {
+    /**
+     * Size in bytes of the stored object.
+     */
+    contentLength?: number;
+    /**
+     * Media type of the stored object (e.g., `\"application/json\"`).
+     */
+    contentType?: string;
+    /**
+     * Unix epoch **milliseconds** for the last modification time.
+     */
+    lastModifiedMs?: number;
+    /**
+     * Opaque entity tag identifying the current stored version.
+     */
+    etag?: string;
+}
+
+export type Path = `/pub/${string}`;
+
 /**
  * A union type of all possible machine-readable codes for the `name` property
- * of a {@link PubkyJsError}.
+ * of a {@link PubkyError}.
  *
  * Provides a simplified, actionable set of error categories for developers
  * to handle in their code.
@@ -55,23 +114,62 @@ export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationEr
  * try {
  *   await client.signup(...);
  * } catch (e) {
- *   const error = e as PubkyJsError;
- *   if (error.name === \'RequestError\' && error.statusCode === 404) {
+ *   const error = e as PubkyError;
+ *   if (
+ *     error.name === \'RequestError\' &&
+ *     typeof error.data === \'object\' &&
+ *     error.data !== null &&
+ *     \'statusCode\' in error.data &&
+ *     (error.data as { statusCode?: number }).statusCode === 404
+ *   ) {
  *     // Handle not found...
  *   }
  * }
  * ```
  */
-export interface PubkyJsError {
+export interface PubkyError {
     name: PubkyErrorName;
     message: string;
     /**
-     * For `RequestError::Server`, this carries the numeric HTTP status code (e.g. 404).
-     * Otherwise `undefined` on the JS side.
+     * Optional structured context associated with the error.
      */
-    statusCode?: number;
+    data?: unknown;
+}
+
+/**
+ * Represents the standard error structure for all exceptions thrown by the Pubky
+ * WASM client.
+ *
+ * @property name - A machine-readable error code from {@link PubkyErrorName}. Use this for programmatic error handling.
+ * @property message - A human-readable, descriptive error message suitable for logging.
+ * @property data - An optional payload containing structured context for an error. For a `RequestError`, this may contain an object with the HTTP status code, e.g., `{ statusCode: 404 }`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.signup(...);
+ * } catch (e) {
+ *   const error = e as PubkyError;
+ *   if (
+ *     error.name === "RequestError" &&
+ *     typeof error.data === "object" &&
+ *     error.data !== null &&
+ *     "statusCode" in error.data &&
+ *     (error.data as { statusCode?: number }).statusCode === 404
+ *   ) {
+ *     // Handle not found...
+ *   }
+ * }
+ * ```
+ */
+export interface PubkyError extends Error {
+  name: PubkyErrorName;
+  message: string;
+  data?: unknown;
 }
 
+export type Address = `pubky${string}/pub/${string}` | `pubky://${string}/pub/${string}`;
+
 /**
  * Pkarr Config
  */
@@ -97,44 +195,11 @@ export interface PubkyClientConfig {
     pkarr?: PkarrConfig;
 }
 
-/**
- * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
- *
- * @typedef {Object} ResourceStats
- * @property {number=} contentLength  Size in bytes.
- * @property {string=} contentType    Media type (e.g. \"application/json; charset=utf-8\").
- * @property {number=} lastModifiedMs Unix epoch milliseconds.
- * @property {string=} etag           Opaque server ETag for the current version.
- *
- * @example
- * const stats = await pubky.publicStorage().stats(`${user}/pub/app/file.json`);
- * if (stats) {
- *   console.log(stats.contentLength, stats.contentType, stats.lastModifiedMs);
- * }
- *
- * Notes:
- * - `contentLength` equals `getBytes(...).length`.
- * - `etag` may be absent and is opaque; compare values to detect updates.
- * - `lastModifiedMs` increases when the resource is updated.
- */
-export interface ResourceStats {
-    /**
-     * Size in bytes of the stored object.
-     */
-    contentLength?: number;
-    /**
-     * Media type of the stored object (e.g., `\"application/json\"`).
-     */
-    contentType?: string;
-    /**
-     * Unix epoch **milliseconds** for the last modification time.
-     */
-    lastModifiedMs?: number;
-    /**
-     * Opaque entity tag identifying the current stored version.
-     */
-    etag?: string;
-}
+export type CapabilityAction = "r" | "w" | "rw";
+export type CapabilityScope = `/${string}`;
+export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
+type CapabilitiesTail = `,${CapabilityEntry}${string}`;
+export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
 
 /**
  * Start and control a pubkyauth authorization flow.
@@ -149,7 +214,7 @@ export class AuthFlow {
   free(): void;
   /**
    * Start a flow (standalone).
-   * Prefer `pubky.startAuthFlow()` to reuse a façade client.
+   * Prefer `pubky.startAuthFlow()` to reuse a facade client.
    *
    * @param {string} capabilities
    * Comma-separated capabilities, e.g. `"/pub/app/:rw,/priv/foo.txt:r"`.
@@ -165,7 +230,7 @@ export class AuthFlow {
    * @returns {AuthFlow}
    * A running auth flow. Call `authorizationUrl()` to show the deep link,
    * then `awaitApproval()` to receive a `Session`.
-   * @throws {PubkyJsError}
+   * @throws {PubkyError}
    * - `{ name: "InvalidInput", message: string }` if any capability entry is invalid
    *     or for an invalid relay URL.
    * @example
@@ -173,23 +238,14 @@ export class AuthFlow {
    * renderQRCode(flow.authorizationUrl());
    * const session = await flow.awaitApproval();
    */
-  static start(capabilities: string, relay?: string | null): AuthFlow;
-  /**
-   * Return the authorization deep link (URL) to show as QR or open on the signer device.
-   *
-   * @returns {string} A `pubkyauth://…` or `https://…` URL with channel info.
-   *
-   * @example
-   * renderQr(flow.authorizationUrl());
-   */
-  authorizationUrl(): string;
+  static start(capabilities: Capabilities, relay?: string | null): AuthFlow;
   /**
    * Block until the user approves on their signer device; returns a `Session`.
    *
    * @returns {Promise<Session>}
    * Resolves when approved; rejects on timeout/cancel/network errors.
    *
-   * @throws {PubkyJsError}
+   * @throws {PubkyError}
    * - `RequestError` if relay/network fails
    * - `AuthenticationError` if approval is denied/invalid
    */
@@ -200,16 +256,25 @@ export class AuthFlow {
    * @returns {Promise<AuthToken>}
    * Resolves when approved; rejects on timeout/cancel/network errors.
    *
-   * @throws {PubkyJsError}
+   * @throws {PubkyError}
    * - `RequestError` if relay/network fails
    */
   awaitToken(): Promise<AuthToken>;
   /**
    * Non-blocking single poll step (advanced UIs).
    *
-   * @returns {Promise<Session|null>} A session if the approval arrived, otherwise `null`.
+   * @returns {Promise<Session|undefined>} A session if the approval arrived, otherwise `undefined`.
    */
   tryPollOnce(): Promise<Session | undefined>;
+  /**
+   * Return the authorization deep link (URL) to show as QR or open on the signer device.
+   *
+   * @returns {string} A `pubkyauth://…` or `https://…` URL with channel info.
+   *
+   * @example
+   * renderQr(flow.authorizationUrl());
+   */
+  readonly authorizationUrl: string;
 }
 /**
  * AuthToken: signed, time-bound proof of key ownership.
@@ -269,15 +334,25 @@ export class AuthToken {
    */
   static fromBytes(bytes: Uint8Array): AuthToken;
   /**
-   * Returns the **public key** that authenticated with this token.
+   * Serialize the token to a `Uint8Array` in its **canonical** (postcard) binary format.
    *
-   * Use `.z32()` on the returned `PublicKey` to get the string form.
+   * Use this to send the token to a backend for verification.
    *
    * ```js
-   * const who = token.publicKey().z32();
+   * const bytes = token.toBytes();
+   * await fetch("/api/verify", { method: "POST", body: bytes });
    * ```
    */
-  publicKey(): PublicKey;
+  toBytes(): Uint8Array;
+  /**
+   * Returns the **public key** that authenticated with this token.
+   *
+   * Use `.z32()` on the returned `PublicKey` to get the string form.
+   *
+   * @example
+   * const who = sessionInfo.publicKey.z32();
+   */
+  readonly publicKey: PublicKey;
   /**
    * Returns the **capabilities** requested by the flow at the time this token was signed.
    *
@@ -288,27 +363,28 @@ export class AuthToken {
    *
    * Example entry: `"/pub/my.app/:rw"`
    */
-  capabilities(): Array<any>;
-  /**
-   * Serialize the token to a `Uint8Array` in its **canonical** (postcard) binary format.
-   *
-   * Use this to send the token to a backend for verification.
-   *
-   * ```js
-   * const bytes = token.toBytes();
-   * await fetch("/api/verify", { method: "POST", body: bytes });
-   * ```
-   */
-  toBytes(): Uint8Array;
+  readonly capabilities: string[];
 }
 /**
- * Low-level HTTP bridge used by the Pubky façade and actors.
+ * Low-level HTTP bridge used by the Pubky facade and actors.
  *
- * - Supports `pubky://<user-z32>/<abs-path>` and `http(s)://` URLs.
+ * - Supports `http(s)://` URLs targeting Pubky or ICANN hosts.
  * - In browsers/undici, passes `credentials: "include"` to send cookies.
  */
 export class Client {
   free(): 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.
    *
@@ -317,7 +393,7 @@ export class Client {
    * `{ pkarr?: { relays?: string[], request_timeout?: number } }`.
    *
    * @returns {Client}
-   * A configured low-level client. Prefer `new Pubky().client()` unless you
+   * A configured low-level client. Prefer `new Pubky().client` unless you
    * need custom relays/timeouts.
    *
    * @throws {InvalidInput}
@@ -333,8 +409,7 @@ export class Client {
   /**
    * Create a client wired for **local testnet**.
    *
-   * Sets PKARR relays to `http://<host>:15411/` and enables WASM `pubky://`
-   * mapping for that host.
+   * Configures PKARR relays for the testnet and remembers the hostname for WASM `_pubky` mapping.
    *
    * @param {string} [host="localhost"]
    * Testnet hostname or IP.
@@ -350,18 +425,28 @@ export class Client {
    * const client = Client.testnet("docker0");  // custom host
    */
   static testnet(host?: string | null): Client;
-  /**
-   * Perform a raw fetch. Works with `pubky://` or `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(`pubky://${user}/pub/app/file.txt`, { method: "PUT", body: "hi", credentials: "include" });
-   */
-  fetch(url: string, init?: any | null): Promise<Promise<any>>;
+}
+export class IntoUnderlyingByteSource {
+  private constructor();
+  free(): void;
+  start(controller: ReadableByteStreamController): void;
+  pull(controller: ReadableByteStreamController): Promise<any>;
+  cancel(): void;
+  readonly type: ReadableStreamType;
+  readonly autoAllocateChunkSize: number;
+}
+export class IntoUnderlyingSink {
+  private constructor();
+  free(): void;
+  write(chunk: any): Promise<any>;
+  close(): Promise<any>;
+  abort(reason: any): Promise<any>;
+}
+export class IntoUnderlyingSource {
+  private constructor();
+  free(): void;
+  pull(controller: ReadableStreamDefaultController): Promise<any>;
+  cancel(): void;
 }
 export class Keypair {
   private constructor();
@@ -378,10 +463,6 @@ export class Keypair {
    * Returns the secret key of this keypair.
    */
   secretKey(): Uint8Array;
-  /**
-   * Returns the [PublicKey] of this keypair.
-   */
-  publicKey(): PublicKey;
   /**
    * Create a recovery file for this keypair (encrypted with the given passphrase).
    */
@@ -390,6 +471,15 @@ export class Keypair {
    * Decrypt a recovery file and return a Keypair (decrypted with the given passphrase).
    */
   static fromRecoveryFile(recovery_file: Uint8Array, passphrase: string): Keypair;
+  /**
+   * Returns the [PublicKey] of this keypair.
+   *
+   * Use `.z32()` on the returned `PublicKey` to get the string form.
+   *
+   * @example
+   * const who = keypair.publicKey.z32();
+   */
+  readonly publicKey: PublicKey;
 }
 /**
  * Resolve/publish `_pubky` PKDNS records (homeserver pointers).
@@ -408,17 +498,17 @@ export class Pkdns {
    * Resolve the homeserver for a given public key (read-only).
    *
    * @param {PublicKey} user
-   * @returns {Promise<string|undefined>} Homeserver public key (z32) or `undefined` if not found.
+   * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
    */
-  getHomeserverOf(pubky: PublicKey): Promise<string | undefined>;
+  getHomeserverOf(pubky: PublicKey): Promise<PublicKey | undefined>;
   /**
    * Resolve the homeserver for **this** user (requires keypair).
    *
-   * @returns {Promise<string|undefined>} Homeserver public key (z32) or `undefined` if not found.
+   * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
    */
-  getHomeserver(): Promise<string | undefined>;
+  getHomeserver(): Promise<PublicKey | undefined>;
   /**
-   * Republish homeserver if record is missing/stale.
+   * Force publish homeserver immediately (even if fresh).
    *
    * Requires keypair or to be signer bound.
    *
@@ -427,7 +517,7 @@ export class Pkdns {
    */
   publishHomeserverForce(host_override?: PublicKey | null): Promise<void>;
   /**
-   * Force publish homeserver immediately (even if fresh).
+   * Republish homeserver if record is missing/stale.
    *
    * Requires keypair or to be signer bound.
    *
@@ -442,10 +532,10 @@ export class Pkdns {
 export class Pubky {
   free(): void;
   /**
-   * Create a Pubky façade wired for **mainnet** defaults (public relays).
+   * Create a Pubky facade wired for **mainnet** defaults (public relays).
    *
    * @returns {Pubky}
-   * A new façade instance. Use this to create signers, start auth flows, etc.
+   * A new facade instance. Use this to create signers, start auth flows, etc.
    *
    * @example
    * const pubky = new Pubky();
@@ -453,7 +543,7 @@ export class Pubky {
    */
   constructor();
   /**
-   * Create a Pubky façade preconfigured for a **local testnet**.
+   * Create a Pubky facade preconfigured for a **local testnet**.
    *
    * If `host` is provided, PKARR and HTTP endpoints are derived as `http://<host>:ports/...`.
    * If omitted, `"localhost"` is assumed (handy for `cargo install pubky-testnet`).
@@ -467,7 +557,7 @@ export class Pubky {
    */
   static testnet(host?: string | null): Pubky;
   /**
-   * Wrap an existing configured HTTP client into a Pubky façade.
+   * Wrap an existing configured HTTP client into a Pubky facade.
    *
    * @param {Client} client A previously constructed client.
    * @returns {Pubky}
@@ -490,19 +580,19 @@ export class Pubky {
    * @param {string} capabilities Comma-separated caps, e.g. `"/pub/app/:rw,/pub/foo/file:r"`.
    * @param {string=} relay Optional HTTP relay base (e.g. `"https://…/link/"`).
    * @returns {AuthFlow}
-   * A running auth flow. Call `authorizationUrl()` to show a QR/deeplink,
+   * A running auth flow. Show `authorizationUrl` as QR/deeplink,
    * then `awaitApproval()` to obtain a `Session`.
    *
-   * @throws {PubkyJsError}
+   * @throws {PubkyError}
    * - `{ name: "InvalidInput" }` for malformed capabilities or bad relay URL
    * - `{ name: "RequestError" }` if the flow cannot be started (network/relay)
    *
    * @example
    * const flow = pubky.startAuthFlow("/pub/my.app/:rw");
-   * renderQr(flow.authorizationUrl());
+   * renderQr(flow.authorizationUrl);
    * const session = await flow.awaitApproval();
    */
-  startAuthFlow(capabilities: string, relay?: string | null): AuthFlow;
+  startAuthFlow(capabilities: Capabilities, relay?: string | null): AuthFlow;
   /**
    * Create a `Signer` from an existing `Keypair`.
    *
@@ -514,6 +604,15 @@ export class Pubky {
    * const session = await signer.signup(homeserverPk, null);
    */
   signer(keypair: Keypair): Signer;
+  /**
+   * Resolve the homeserver for a given public key (read-only).
+   *
+   * Uses an internal read-only Pkdns actor.
+   *
+   * @param {PublicKey} user
+   * @returns {Promise<PublicKey|undefined>} Homeserver public key (z32) or `undefined` if not found.
+   */
+  getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>;
   /**
    * Public, unauthenticated storage API.
    *
@@ -523,20 +622,9 @@ export class Pubky {
    * @returns {PublicStorage}
    *
    * @example
-   * const pub = pubky.publicStorage();
-   * const text = await pub.getText(`${userPk.z32()}/pub/example.com/hello.txt`);
-   */
-  publicStorage(): PublicStorage;
-  /**
-   * Read-only PKDNS (Pkarr) resolver.
-   *
-   * @returns {Pkdns}
-   *
-   * @example
-   * const dns = pubky.pkdns();
-   * const homeserver = await dns.getHomeserverOf(userPk);
+   * const text = await pubky.publicStorage.getText(`${userPk.z32()}/pub/example.com/hello.txt`);
    */
-  pkdns(): Pkdns;
+  readonly publicStorage: PublicStorage;
   /**
    * Access the underlying HTTP client (advanced).
    *
@@ -544,9 +632,9 @@ 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://${user}/pub/app/file.txt`, { credentials: "include" });
    */
-  client(): Client;
+  readonly client: Client;
 }
 export class PublicKey {
   private constructor();
@@ -574,80 +662,87 @@ export class PublicStorage {
    */
   constructor();
   /**
-   * List a directory. Results are `pubky://…` absolute URLs.
+   * List a directory. Results are `pubky://…` identifier URLs.
    *
-   * @param {string} address Addressed directory (must end with `/`).
+   * @param {Address} address Addressed directory (must end with `/`).
    * @param {string|null=} cursor Optional suffix or full URL to start **after**.
    * @param {boolean=} reverse Default `false`. When `true`, newest/lexicographically-last first.
    * @param {number=} limit Optional result limit.
    * @param {boolean=} shallow Default `false`. When `true`, lists only first-level entries.
    * @returns {Promise<string[]>}
    */
-  list(address: string, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+  list(address: Address, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+  /**
+   * Perform a streaming `GET` and expose the raw `Response` object.
+   *
+   * @param {Address} address
+   * @returns {Promise<Response>}
+   */
+  get(address: Address): Promise<Response>;
   /**
    * Fetch bytes from an addressed path.
    *
-   * @param {string} address
+   * @param {Address} address
    * @returns {Promise<Uint8Array>}
    */
-  getBytes(address: string): Promise<Uint8Array>;
+  getBytes(address: Address): Promise<Uint8Array>;
   /**
    * Fetch text from an addressed path as UTF-8 text.
    *
-   * @param {string} address
+   * @param {Address} address
    * @returns {Promise<string>}
    */
-  getText(address: string): Promise<string>;
+  getText(address: Address): Promise<string>;
   /**
    * Fetch JSON from an addressed path.
    *
-   * @param {string} address `"<user-z32>/pub/.../file.json"` or `pubky://<user>/pub/...`.
+   * @param {Address} address `"pubky<user>/pub/.../file.json"` (preferred) or `pubky://<user>/pub/...`.
    * @returns {Promise<any>}
    */
-  getJson(address: string): Promise<any>;
+  getJson(address: Address): Promise<any>;
   /**
    * Check if a path exists.
    *
-   * @param {string} address
+   * @param {Address} address
    * @returns {Promise<boolean>}
    */
-  exists(address: string): Promise<boolean>;
+  exists(address: Address): Promise<boolean>;
   /**
    * Get metadata for an address
    *
-   * @param {string} address `"<user-z32>/pub/.../file.json"` or `pubky://<user>/pub/...`.
+   * @param {Address} address `"pubky<user>/pub/.../file.json"` (preferred) or `pubky://<user>/pub/...`.
    * @returns {Promise<ResourceStats|undefined>} `undefined` if the resource does not exist.
-   * @throws {PubkyJsError} On invalid input or transport/server errors.
+   * @throws {PubkyError} On invalid input or transport/server errors.
    */
-  stats(address: string): Promise<ResourceStats | undefined>;
+  stats(address: Address): Promise<ResourceStats | undefined>;
 }
 /**
  * An authenticated context “as the user”.
- * - Use `storage()` for reads/writes (absolute paths like `/pub/app/file.txt`)
+ * - Use `storage` for reads/writes (absolute paths like `/pub/app/file.txt`)
  * - Cookie is managed automatically by the underlying fetch client
  */
 export class Session {
   private constructor();
   free(): void;
+  /**
+   * Invalidate the session on the server (clears server cookie).
+   * Further calls to storage API will fail.
+   *
+   * @returns {Promise<void>}
+   */
+  signout(): Promise<void>;
   /**
    * Retrieve immutable info about this session (user & capabilities).
    *
    * @returns {SessionInfo}
    */
-  info(): SessionInfo;
+  readonly info: SessionInfo;
   /**
    * Access the session-scoped storage API (read/write).
    *
    * @returns {SessionStorage}
    */
-  storage(): SessionStorage;
-  /**
-   * Invalidate the session on the server (clears server cookie).
-   * It also consumes this JS/Wasm Session. Further calls will fail.
-   *
-   * @returns {Promise<void>}
-   */
-  signout(): Promise<void>;
+  readonly storage: SessionStorage;
 }
 /**
  * Static snapshot of session metadata.
@@ -658,15 +753,20 @@ export class SessionInfo {
   /**
    * The user’s public key for this session.
    *
+   * Use `.z32()` on the returned `PublicKey` to get the string form.
+   *
    * @returns {PublicKey}
+   *
+   * @example
+   * const who = sessionInfo.publicKey.z32();
    */
-  publicKey(): PublicKey;
+  readonly publicKey: PublicKey;
   /**
    * Effective capabilities granted to this session.
    *
    * @returns {string[]} Normalized capability entries (e.g. `"/pub/app/:rw"`).
    */
-  capabilities(): string[];
+  readonly capabilities: string[];
 }
 /**
  * Read/write storage scoped to **your** session (absolute paths: `/pub/...`).
@@ -677,81 +777,88 @@ export class SessionStorage {
   /**
    * List a directory (absolute session path). Returns `pubky://…` URLs.
    *
-   * @param {string} path Must end with `/`.
+   * @param {Path} path Must end with `/`.
    * @param {string|null=} cursor Optional suffix or full URL to start **after**.
    * @param {boolean=} reverse Default `false`.
    * @param {number=} limit Optional result limit.
    * @param {boolean=} shallow Default `false`.
    * @returns {Promise<string[]>}
    */
-  list(path: string, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+  list(path: Path, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+  /**
+   * GET a streaming response for an absolute session path.
+   *
+   * @param {Path} path
+   * @returns {Promise<Response>}
+   */
+  get(path: Path): Promise<Response>;
   /**
    * GET bytes from an absolute session path.
    *
-   * @param {string} path
+   * @param {Path} path
    * @returns {Promise<Uint8Array>}
    */
-  getBytes(path: string): Promise<Uint8Array>;
+  getBytes(path: Path): Promise<Uint8Array>;
   /**
    * GET text from an absolute session path.
    *
-   * @param {string} path
+   * @param {Path} path
    * @returns {Promise<string>}
    */
-  getText(path: string): Promise<string>;
+  getText(path: Path): Promise<string>;
   /**
    * GET JSON from an absolute session path.
    *
-   * @param {string} path
+   * @param {Path} path
    * @returns {Promise<any>}
    */
-  getJson(addr: string): Promise<any>;
+  getJson(path: Path): Promise<any>;
   /**
    * Check existence.
    *
-   * @param {string} path
+   * @param {Path} path
    * @returns {Promise<boolean>}
    */
-  exists(path: string): Promise<boolean>;
+  exists(path: Path): Promise<boolean>;
   /**
    * Get metadata for an absolute, session-scoped path (e.g. `"/pub/app/file.json"`).
    *
-   * @param {string} path Absolute path under your user (starts with `/`).
+   * @param {Path} path Absolute path under your user (starts with `/`).
    * @returns {Promise<ResourceStats|undefined>} `undefined` if the resource does not exist.
-   * @throws {PubkyJsError} On invalid input or transport/server errors.
+   * @throws {PubkyError} On invalid input or transport/server errors.
    */
-  stats(path: string): Promise<ResourceStats | undefined>;
+  stats(path: Path): Promise<ResourceStats | undefined>;
   /**
    * PUT binary at an absolute session path.
    *
-   * @param {string} path
+   * @param {Path} path
    * @param {Uint8Array} bytes
    * @returns {Promise<void>}
    */
-  putBytes(path: string, body: Uint8Array): Promise<void>;
+  putBytes(path: Path, body: Uint8Array): Promise<void>;
   /**
    * PUT text at an absolute session path.
    *
-   * @param {string} path
+   * @param {Path} path
    * @param {string} text
    * @returns {Promise<void>}
    */
-  putText(path: string, body: string): Promise<void>;
+  putText(path: Path, body: string): Promise<void>;
   /**
    * PUT JSON at an absolute session path.
    *
-   * @param {string} path Absolute path (e.g. `"/pub/app/data.json"`).
+   * @param {Path} path Absolute path (e.g. `"/pub/app/data.json"`).
    * @param {any} value JSON-serializable value.
    * @returns {Promise<void>}
    */
-  putJson(path: string, body: any): Promise<void>;
+  putJson(path: Path, body: any): Promise<void>;
   /**
    * Delete a path (file or empty directory).
    *
-   * @param {string} path
+   * @param {Path} path
    * @returns {Promise<void>}
    */
-  delete(path: string): Promise<void>;
+  delete(path: Path): Promise<void>;
 }
 /**
  * Holds a user’s `Keypair` and performs identity operations:
@@ -770,12 +877,6 @@ export class Signer {
    * @returns {Signer}
    */
   static fromKeypair(keypair: Keypair): Signer;
-  /**
-   * Get the public key of this signer.
-   *
-   * @returns {PublicKey}
-   */
-  publicKey(): PublicKey;
   /**
    * Sign up at a homeserver. Returns a ready `Session`.
    *
@@ -785,7 +886,7 @@ export class Signer {
    * @param {string|null} signupToken Invite/registration token or `null`.
    * @returns {Promise<Session>}
    *
-   * @throws {PubkyJsError}
+   * @throws {PubkyError}
    * - `AuthenticationError` (bad/expired token)
    * - `RequestError` (network/server)
    */
@@ -797,7 +898,7 @@ export class Signer {
    *
    * @returns {Promise<Session>}
    *
-   * @throws {PubkyJsError}
+   * @throws {PubkyError}
    */
   signin(): Promise<Session>;
   /**
@@ -812,10 +913,19 @@ export class Signer {
    * Approve a `pubkyauth://` request URL (encrypts & POSTs the signed AuthToken).
    */
   approveAuthRequest(pubkyauth_url: string): Promise<void>;
+  /**
+   * Get the public key of this signer.
+   *
+   * @returns {PublicKey}
+   */
+  readonly publicKey: PublicKey;
   /**
    * Get a PKDNS actor bound to this signer's client & keypair (publishing enabled).
    *
    * @returns {Pkdns}
+   *
+   * @example
+   * await signer.pkdns.publishHomeserverIfStale(homeserverPk);
    */
-  pkdns(): Pkdns;
+  readonly pkdns: Pkdns;
 }