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

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,58 @@ 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";
+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}`;
+type CapabilitiesTail = `,${CapabilityEntry}${string}`;
+export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
+
 /**
  * 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,46 +108,58 @@ 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.
-     */
-    statusCode?: number;
-}
-
-/**
- * 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.
+     * Optional structured context associated with the error.
      */
-    requestTimeout?: number;
+    data?: unknown;
 }
 
 /**
- * Pubky Client Config
+ * 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 PubkyClientConfig {
-    /**
-     * Configuration on how to access pkarr packets on the mainline DHT.
-     */
-    pkarr?: PkarrConfig;
+export interface PubkyError extends Error {
+  name: PubkyErrorName;
+  message: string;
+  data?: unknown;
 }
 
 /**
@@ -107,7 +172,7 @@ export interface PubkyClientConfig {
  * @property {string=} etag           Opaque server ETag for the current version.
  *
  * @example
- * const stats = await pubky.publicStorage().stats(`${user}/pub/app/file.json`);
+ * const stats = await pubky.publicStorage.stats(`${user}/pub/app/file.json`);
  * if (stats) {
  *   console.log(stats.contentLength, stats.contentType, stats.lastModifiedMs);
  * }
@@ -147,17 +212,25 @@ export interface ResourceStats {
 export class AuthFlow {
   private constructor();
   free(): void;
+  [Symbol.dispose](): 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"`.
    * Each entry must be `"<scope>:<actions>"`, where:
-   * - `scope` starts with `/` (e.g. `/pub/example.app/`)
+   * - `scope` starts with `/` (e.g. `/pub/example.com/`)
    * - `actions` is any combo of `r` and/or `w` (order is normalized; `wr` -> `rw`)
    * Empty string is allowed (no scopes).
    *
+   * @param {AuthFlowKind} kind
+   * The kind of authentication flow to perform.
+   * This can either be a sign in or a sign up flow.
+   * Examples:
+   * - `AuthFlowKind.signin()` - Sign in to an existing account.
+   * - `AuthFlowKind.signup(homeserverPublicKey, signupToken)` - Sign up for a new account.
+   *
    * @param {string} [relay]
    * Optional HTTP relay base, e.g. `"https://demo.httprelay.io/link/"`.
    * Defaults to the default Synonym-hosted relay when omitted.
@@ -165,31 +238,22 @@ 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
-   * const flow = AuthFlow.start("/pub/my.app/:rw,/pub/pubky.app/:w");
+   * const flow = AuthFlow.start("/pub/my-cool-app/:rw,/pub/pubky.app/:w");
    * 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, kind: AuthFlowKind, 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 +264,52 @@ 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;
+}
+/**
+ * The kind of authentication flow to perform.
+ * This can either be a sign in or a sign up flow.
+ */
+export class AuthFlowKind {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Create a sign in flow.
+   */
+  static signin(): AuthFlowKind;
+  /**
+   * Create a sign up flow.
+   * # Arguments
+   * * `homeserver_public_key` - The public key of the homeserver to sign up on.
+   * * `signup_token` - The signup token to use for the signup flow. This is optional.
+   */
+  static signup(homeserver_public_key: PublicKey, signup_token?: string | null): AuthFlowKind;
+  /**
+   * Get the intent of the authentication flow.
+   * # Returns
+   * * `"signin"` - If the authentication flow is a sign in flow.
+   * * `"signup"` - If the authentication flow is a sign up flow.
+   */
+  readonly intent: string;
 }
 /**
  * AuthToken: signed, time-bound proof of key ownership.
@@ -240,6 +340,7 @@ export class AuthFlow {
 export class AuthToken {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Parse and verify an `AuthToken` from its canonical bytes.
    *
@@ -269,15 +370,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.
    *
@@ -286,29 +397,19 @@ export class AuthToken {
    *
    * Returns: `string[]`, where each item is the canonical entry `"<scope>:<actions>"`.
    *
-   * 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 });
-   * ```
+   * Example entry: `"/pub/my-cool-app/:rw"`
    */
-  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;
+  [Symbol.dispose](): void;
   /**
    * Create a Pubky HTTP client.
    *
@@ -317,7 +418,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 +434,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.
@@ -351,21 +451,47 @@ export class Client {
    */
   static testnet(host?: string | null): Client;
   /**
-   * Perform a raw fetch. Works with `pubky://` or `http(s)://` URLs.
+   * 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.
+   * @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" });
+   * 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?: any | null): Promise<Promise<any>>;
+  fetch(url: string, init?: RequestInit | null): Promise<Response>;
+}
+export class IntoUnderlyingByteSource {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): 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;
+  [Symbol.dispose](): void;
+  write(chunk: any): Promise<any>;
+  close(): Promise<any>;
+  abort(reason: any): Promise<any>;
+}
+export class IntoUnderlyingSource {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  pull(controller: ReadableStreamDefaultController): Promise<any>;
+  cancel(): void;
 }
 export class Keypair {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Generate a random [Keypair]
    */
@@ -378,10 +504,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,12 +512,22 @@ 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).
  */
 export class Pkdns {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Read-only PKDNS actor (no keypair; resolve only).
    */
@@ -408,17 +540,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 +559,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.
    *
@@ -441,11 +573,12 @@ export class Pkdns {
  */
 export class Pubky {
   free(): void;
+  [Symbol.dispose](): 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 +586,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 +600,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}
@@ -483,26 +616,30 @@ export class Pubky {
    * Provide a **capabilities string** and (optionally) a relay base URL.
    * The capabilities string is a comma-separated list of entries:
    * `"<scope>:<actions>"`, where:
-   * - `scope` starts with `/` (e.g. `/pub/example.app/`).
+   * - `scope` starts with `/` (e.g. `/pub/example.com/`).
    * - `actions` is any combo of `r` and/or `w` (order normalized; `wr` -> `rw`).
    * Pass `""` for no scopes (read-only public session).
    *
    * @param {string} capabilities Comma-separated caps, e.g. `"/pub/app/:rw,/pub/foo/file:r"`.
+   * @param {AuthFlowKind} kind The kind of authentication flow to perform.
+   * Examples:
+   * - `AuthFlowKind.signin()` - Sign in to an existing account.
+   * - `AuthFlowKind.signup(homeserverPublicKey, signupToken)` - Sign up for a new account.
    * @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());
+   * const flow = pubky.startAuthFlow("/pub/my-cool-app/:rw");
+   * renderQr(flow.authorizationUrl);
    * const session = await flow.awaitApproval();
    */
-  startAuthFlow(capabilities: string, relay?: string | null): AuthFlow;
+  startAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
   /**
    * Create a `Signer` from an existing `Keypair`.
    *
@@ -515,28 +652,40 @@ export class Pubky {
    */
   signer(keypair: Keypair): Signer;
   /**
-   * Public, unauthenticated storage API.
+   * Resolve the homeserver for a given public key (read-only).
    *
-   * Use for **read-only** public access via addressed paths:
-   * `"<user-z32>/pub/…"`.
+   * Uses an internal read-only Pkdns actor.
    *
-   * @returns {PublicStorage}
+   * @param {PublicKey} user
+   * @returns {Promise<PublicKey|undefined>} Homeserver public key (z32) or `undefined` if not found.
+   */
+  getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>;
+  /**
+   * Restore a session from a previously exported snapshot, using this instance's client.
+   *
+   * This does **not** read or write any secrets. It revalidates the session metadata with
+   * the server using the browser-managed HTTP-only cookie that must still be present.
+   *
+   * @param {string} exported A string produced by `session.export()`.
+   * @returns {Promise<Session>}
+   * A rehydrated session bound to this SDK's HTTP client.
    *
    * @example
-   * const pub = pubky.publicStorage();
-   * const text = await pub.getText(`${userPk.z32()}/pub/example.com/hello.txt`);
+   * const restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
    */
-  publicStorage(): PublicStorage;
+  restoreSession(exported: string): Promise<Session>;
   /**
-   * Read-only PKDNS (Pkarr) resolver.
+   * Public, unauthenticated storage API.
    *
-   * @returns {Pkdns}
+   * Use for **read-only** public access via addressed paths:
+   * `"<user-z32>/pub/…"`.
+   *
+   * @returns {PublicStorage}
    *
    * @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,13 +693,14 @@ 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();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Convert the PublicKey to Uint8Array
    */
@@ -569,85 +719,125 @@ export class PublicKey {
  */
 export class PublicStorage {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Construct PublicStorage using global client (mainline relays).
    */
   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>;
+}
+export class SeedExportDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SeedExportDeepLink;
+  toString(): string;
+  readonly secret: Uint8Array;
 }
 /**
  * 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;
+  [Symbol.dispose](): void;
+  /**
+   * Invalidate the session on the server (clears server cookie).
+   * Further calls to storage API will fail.
+   *
+   * @returns {Promise<void>}
+   */
+  signout(): Promise<void>;
+  /**
+   * Export the session metadata so it can be restored after a tab refresh.
+   *
+   * The export string contains **no secrets**; it only serializes the public `SessionInfo`.
+   * Browsers remain responsible for persisting the HTTP-only session cookie.
+   *
+   * @returns {string}
+   * A base64 string to store (e.g. in `localStorage`).
+   */
+  export(): string;
+  /**
+   * Restore a session from an `export()` string.
+   *
+   * The HTTP-only cookie must still be present in the browser; this function does not
+   * read or write any secrets.
+   *
+   * @param {string} exported
+   * A string produced by `session.export()`.
+   * @param {Client=} client
+   * Optional client to reuse transport configuration.
+   * @returns {Promise<Session>}
+   */
+  static restore(exported: string, client?: Client | null): Promise<Session>;
   /**
    * 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.
@@ -655,18 +845,24 @@ export class Session {
 export class SessionInfo {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * 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/...`).
@@ -674,84 +870,92 @@ export class SessionInfo {
 export class SessionStorage {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * 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:
@@ -763,6 +967,7 @@ export class SessionStorage {
 export class Signer {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Create a signer from a `Keypair` (prefer `pubky.signer(kp)`).
    *
@@ -770,12 +975,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 +984,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 +996,7 @@ export class Signer {
    *
    * @returns {Promise<Session>}
    *
-   * @throws {PubkyJsError}
+   * @throws {PubkyError}
    */
   signin(): Promise<Session>;
   /**
@@ -812,10 +1011,41 @@ 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;
+}
+export class SigninDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SigninDeepLink;
+  toString(): string;
+  readonly capabilities: string;
+  readonly baseRelayUrl: string;
+  readonly secret: Uint8Array;
+}
+export class SignupDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SignupDeepLink;
+  toString(): string;
+  readonly capabilities: string;
+  readonly baseRelayUrl: string;
+  readonly secret: Uint8Array;
+  readonly homeserver: PublicKey;
+  readonly signupToken: string | undefined;
 }