@synonymdev/pubky 0.6.0 → 0.8.0

package/pubky.d.ts

@@ -1,64 +1,17 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
- * Set the global logging verbosity for the WASM Pubky SDK. Routes Rust `log` output to the browser console.
- *
- * 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 {Level} level
- *        Minimum log level to enable. One of: "error" | "warn" | "info" | "debug" | "trace".
- *
- * @returns {void}
- *
- * @throws {Error}
- *         If `level` is invalid ("Invalid log level") or the logger cannot be initialized
- *         (e.g., already initialized).
- *
- * Usage:
- *   Call once at application startup, before invoking other SDK APIs.
- */
-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.
- *
- * - Normalizes action order (`wr` -> `rw`)
- * - Throws `InvalidInput` listing malformed entries.
- *
- * @param {string} input
- * @returns {string} Normalized string (same shape as input).
- * @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 CapabilityAction = "r" | "w" | "rw";
-export type CapabilityScope = `/${string}`;
-export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
-type CapabilitiesTail = `,${CapabilityEntry}${string}`;
-export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
 
+type ReadableStreamType = "bytes";
 /**
  * A union type of all possible machine-readable codes for the `name` property
  * of a {@link PubkyError}.
@@ -68,6 +21,31 @@ export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${Capabilit
  */
 export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationError" | "PkarrError" | "ClientStateError" | "InternalError";
 
+/**
+ * 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;
+}
+
 /**
  * Represents the standard error structure for all exceptions thrown by the Pubky
  * WASM client.
@@ -83,10 +61,10 @@ export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationEr
  * } catch (e) {
  *   const error = e as PubkyError;
  *   if (
- *     error.name === \'RequestError\' &&
- *     typeof error.data === \'object\' &&
+ *     error.name === "RequestError" &&
+ *     typeof error.data === "object" &&
  *     error.data !== null &&
- *     \'statusCode\' in error.data &&
+ *     "statusCode" in error.data &&
  *     (error.data as { statusCode?: number }).statusCode === 404
  *   ) {
  *     // Handle not found...
@@ -94,12 +72,9 @@ export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationEr
  * }
  * ```
  */
-export interface PubkyError {
+export interface PubkyError extends Error {
     name: PubkyErrorName;
     message: string;
-    /**
-     * Optional structured context associated with the error.
-     */
     data?: unknown;
 }
 
@@ -118,10 +93,10 @@ export interface PubkyError {
  * } catch (e) {
  *   const error = e as PubkyError;
  *   if (
- *     error.name === "RequestError" &&
- *     typeof error.data === "object" &&
+ *     error.name === \'RequestError\' &&
+ *     typeof error.data === \'object\' &&
  *     error.data !== null &&
- *     "statusCode" in error.data &&
+ *     \'statusCode\' in error.data &&
  *     (error.data as { statusCode?: number }).statusCode === 404
  *   ) {
  *     // Handle not found...
@@ -129,37 +104,13 @@ export interface PubkyError {
  * }
  * ```
  */
-export interface PubkyError extends Error {
-  name: PubkyErrorName;
-  message: string;
-  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 {
+export interface PubkyError {
+    name: PubkyErrorName;
+    message: string;
     /**
-     * Configuration on how to access pkarr packets on the mainline DHT.
+     * Optional structured context associated with the error.
      */
-    pkarr?: PkarrConfig;
+    data?: unknown;
 }
 
 /**
@@ -201,6 +152,17 @@ export interface ResourceStats {
     etag?: string;
 }
 
+export type Address = `pubky${string}/pub/${string}` | `pubky://${string}/pub/${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}`;
+
+export type Path = `/pub/${string}`;
+
+
 /**
  * Start and control a pubkyauth authorization flow.
  *
@@ -210,107 +172,129 @@ export interface ResourceStats {
  * 3) `awaitApproval()` to receive a ready `Session`
  */
 export class AuthFlow {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Start a flow (standalone).
-   * 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.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.
-   *
-   * @returns {AuthFlow}
-   * A running auth flow. Call `authorizationUrl()` to show the deep link,
-   * then `awaitApproval()` to receive a `Session`.
-   * @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-cool-app/:rw,/pub/pubky.app/:w");
-   * renderQRCode(flow.authorizationUrl());
-   * const session = await flow.awaitApproval();
-   */
-  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 {PubkyError}
-   * - `RequestError` if relay/network fails
-   * - `AuthenticationError` if approval is denied/invalid
-   */
-  awaitApproval(): Promise<Session>;
-  /**
-   * Block until the user approves on their signer device; returns an `AuthToken`.
-   *
-   * @returns {Promise<AuthToken>}
-   * Resolves when approved; rejects on timeout/cancel/network errors.
-   *
-   * @throws {PubkyError}
-   * - `RequestError` if relay/network fails
-   */
-  awaitToken(): Promise<AuthToken>;
-  /**
-   * Non-blocking single poll step (advanced UIs).
-   *
-   * @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;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * 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 {PubkyError}
+     * - `RequestError` if relay/network fails
+     * - `AuthenticationError` if approval is denied/invalid
+     */
+    awaitApproval(): Promise<Session>;
+    /**
+     * Block until the user approves on their signer device; returns an `AuthToken`.
+     *
+     * @returns {Promise<AuthToken>}
+     * Resolves when approved; rejects on timeout/cancel/network errors.
+     *
+     * @throws {PubkyError}
+     * - `RequestError` if relay/network fails
+     */
+    awaitToken(): Promise<AuthToken>;
+    /**
+     * Resume a previously started auth flow from its saved `authorizationUrl` (standalone).
+     * Prefer `pubky.resumeAuthFlow()` to reuse a facade client; this creates a default (mainnet) client.
+     *
+     * Relay messages expire after ~5 minutes; resume is only viable in that window.
+     * See `Pubky.resumeAuthFlow()` / `Pubky.startAuthFlow()` for full guidance.
+     *
+     * **Security:** `authorizationUrl` contains the `client_secret`.
+     * Delete it from storage as soon as resume completes or is abandoned.
+     *
+     * @param {string} authorizationUrl The `pubkyauth://…` URL from a previous flow.
+     * @returns {AuthFlow} A flow reconnected to the original relay channel.
+     * @throws {PubkyError}
+     * - `{ name: "AuthenticationError" }` if the URL is invalid or not a signin/signup link
+     */
+    static resume(authorization_url: string): AuthFlow;
+    /**
+     * Start a flow (standalone).
+     * 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.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/inbox/"`.
+     * Defaults to the default Synonym-hosted relay when omitted.
+     *
+     * @returns {AuthFlow}
+     * A running auth flow. Call `authorizationUrl()` to show the deep link,
+     * then `awaitApproval()` to receive a `Session`.
+     * @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-cool-app/:rw,/pub/pubky.app/:w");
+     * renderQRCode(flow.authorizationUrl());
+     * const session = await flow.awaitApproval();
+     */
+    static start(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
+    /**
+     * Non-blocking single poll step (advanced UIs).
+     *
+     * @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.
+     *
+     * **Security:** This URL contains the `client_secret` in plaintext.
+     * Treat it as a short-lived secret and delete it after the flow completes.
+     * See `Pubky.startAuthFlow()` docs for storage guidance.
+     *
+     * @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;
+    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.
  *
@@ -338,70 +322,71 @@ export class AuthFlowKind {
  * `Uint8Array`, and [`AuthToken.verify()`] to parse + verify on the server.
  */
 export class AuthToken {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Parse and verify an `AuthToken` from its canonical bytes.
-   *
-   * - Verifies version, timestamp freshness window, and signature.
-   * - Throws on invalid/expired/unknown version.
-   *
-   * Use this on your server after receiving `Uint8Array` from the client.
-   *
-   * ```js
-   * import { AuthToken } from "@synonymdev/pubky";
-   *
-   * 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().toString(), { status: 200 });
-   * }
-   * ```
-   */
-  static verify(bytes: Uint8Array): AuthToken;
-  /**
-   * Deserialize an `AuthToken` **without** verification.
-   *
-   * Most apps should call [`AuthToken.verify()`]. This is provided for tooling or diagnostics
-   * where you want to inspect the structure first.
-   *
-   * Throws if the bytes cannot be parsed as a valid serialized token.
-   */
-  static fromBytes(bytes: Uint8Array): AuthToken;
-  /**
-   * 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;
-  /**
-   * Returns the **public key** that authenticated with this token.
-   *
-   * 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 = token.publicKey.toString();
-   */
-  readonly publicKey: PublicKey;
-  /**
-   * Returns the **capabilities** requested by the flow at the time this token was signed.
-   *
-   * Most auth-only flows pass an empty string to `startAuthFlow("", relay)`, so this will
-   * commonly be an empty array.
-   *
-   * Returns: `string[]`, where each item is the canonical entry `"<scope>:<actions>"`.
-   *
-   * Example entry: `"/pub/my-cool-app/:rw"`
-   */
-  readonly capabilities: string[];
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Deserialize an `AuthToken` **without** verification.
+     *
+     * Most apps should call [`AuthToken.verify()`]. This is provided for tooling or diagnostics
+     * where you want to inspect the structure first.
+     *
+     * Throws if the bytes cannot be parsed as a valid serialized token.
+     */
+    static fromBytes(bytes: Uint8Array): AuthToken;
+    /**
+     * 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;
+    /**
+     * Parse and verify an `AuthToken` from its canonical bytes.
+     *
+     * - Verifies version, timestamp freshness window, and signature.
+     * - Throws on invalid/expired/unknown version.
+     *
+     * Use this on your server after receiving `Uint8Array` from the client.
+     *
+     * ```js
+     * import { AuthToken } from "@synonymdev/pubky";
+     *
+     * 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().toString(), { status: 200 });
+     * }
+     * ```
+     */
+    static verify(bytes: Uint8Array): AuthToken;
+    /**
+     * Returns the **capabilities** requested by the flow at the time this token was signed.
+     *
+     * Most auth-only flows pass an empty string to `startAuthFlow("", relay)`, so this will
+     * commonly be an empty array.
+     *
+     * Returns: `string[]`, where each item is the canonical entry `"<scope>:<actions>"`.
+     *
+     * Example entry: `"/pub/my-cool-app/:rw"`
+     */
+    readonly capabilities: string[];
+    /**
+     * Returns the **public key** that authenticated with this token.
+     *
+     * 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 = token.publicKey.toString();
+     */
+    readonly publicKey: PublicKey;
 }
+
 /**
  * Low-level HTTP bridge used by the Pubky facade and actors.
  *
@@ -409,567 +394,872 @@ export class AuthToken {
  * - In browsers/undici, passes `credentials: "include"` to send cookies.
  */
 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.
-   *
-   * @param {PubkyClientConfig} [config]
-   * Optional transport overrides:
-   * `{ pkarr?: { relays?: string[], request_timeout?: number } }`.
-   *
-   * @returns {Client}
-   * A configured low-level client. Prefer `new Pubky().client` unless you
-   * need custom relays/timeouts.
-   *
-   * @throws {InvalidInput}
-   * If any PKARR relay URL is invalid.
-   *
-   * @example
-   * const client = new Client({
-   *   pkarr: { relays: ["https://relay1/","https://relay2/"], request_timeout: 8000 }
-   * });
-   * const pubky = Pubky.withClient(client);
-   */
-  constructor(config_opt?: PubkyClientConfig | null);
-  /**
-   * Create a client wired for **local testnet**.
-   *
-   * Configures PKARR relays for the testnet and remembers the hostname for WASM `_pubky` mapping.
-   *
-   * @param {string} [host="localhost"]
-   * Testnet hostname or IP.
-   *
-   * @returns {Client}
-   * A client ready to talk to your local testnet.
-   *
-   * @example
-   * const client = Client.testnet();           // localhost
-   * const pubky  = Pubky.withClient(client);
-   *
-   * @example
-   * const client = Client.testnet("docker0");  // custom host
-   */
-  static testnet(host?: string | null): 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.
+     *
+     * @param {PubkyClientConfig} [config]
+     * Optional transport overrides:
+     * `{ pkarr?: { relays?: string[], request_timeout?: number } }`.
+     *
+     * @returns {Client}
+     * A configured low-level client. Prefer `new Pubky().client` unless you
+     * need custom relays/timeouts.
+     *
+     * @throws {InvalidInput}
+     * If any PKARR relay URL is invalid.
+     *
+     * @example
+     * const client = new Client({
+     *   pkarr: { relays: ["https://relay1/","https://relay2/"], request_timeout: 8000 }
+     * });
+     * const pubky = Pubky.withClient(client);
+     */
+    constructor(config_opt?: PubkyClientConfig | null);
+    /**
+     * Create a client wired for **local testnet**.
+     *
+     * Configures PKARR relays for the testnet and remembers the hostname for WASM `_pubky` mapping.
+     *
+     * @param {string} [host="localhost"]
+     * Testnet hostname or IP.
+     *
+     * @returns {Client}
+     * A client ready to talk to your local testnet.
+     *
+     * @example
+     * const client = Client.testnet();           // localhost
+     * const pubky  = Pubky.withClient(client);
+     *
+     * @example
+     * const client = Client.testnet("docker0");  // custom host
+     */
+    static testnet(host?: string | null): Client;
+}
+
+/**
+ * A single event from the event stream.
+ *
+ * @example
+ * ```typescript
+ * for await (const event of stream) {
+ *   console.log(event.eventType);  // "PUT" or "DEL"
+ *   console.log(event.cursor);     // cursor string for pagination
+ *
+ *   if (event.eventType === "PUT") {
+ *     console.log("Hash:", event.contentHash);
+ *   }
+ *
+ *   // Access resource details
+ *   console.log(event.resource.owner.z32()); // User's public key
+ *   console.log(event.resource.path);        // "/pub/example.txt"
+ *   console.log(event.resource.toPubkyUrl()); // Full pubky:// URL
+ * }
+ * ```
+ */
+export class Event {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Get the content hash (only for PUT events).
+     * Returns the blake3 hash in base64 format, or undefined for DELETE events.
+     */
+    readonly contentHash: string | undefined;
+    /**
+     * Get the cursor for pagination.
+     */
+    readonly cursor: string;
+    /**
+     * Get the event type ("PUT" or "DEL").
+     */
+    readonly eventType: string;
+    /**
+     * Get the resource that was created, updated, or deleted.
+     */
+    readonly resource: PubkyResource;
 }
+
+/**
+ * Builder for creating an event stream subscription.
+ *
+ * Construct via `Pubky.eventStreamForUser()` or `Pubky.eventStreamFor()`.
+ *
+ * @example
+ * ```typescript
+ * const stream = await pubky.eventStreamForUser(userPubkey, null)
+ *   .live()
+ *   .limit(100)
+ *   .path("/pub/")
+ *   .subscribe();
+ *
+ * for await (const event of stream) {
+ *   console.log(event.eventType, event.resource.path);
+ * }
+ * ```
+ */
+export class EventStreamBuilder {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Add multiple users to the event stream subscription at once.
+     *
+     * Each user can have an independent cursor position. If a user already exists,
+     * their cursor value is overwritten.
+     *
+     * @param {Array<[string, string | null]>} users - Array of [z32PublicKey, cursor] tuples
+     * @returns {EventStreamBuilder} - Builder for chaining
+     * @throws {Error} - If total users would exceed 50 or if any cursor/pubkey is invalid
+     *
+     * @example
+     * ```typescript
+     * const users: [string, string | null][] = [
+     *   [user1.z32(), null],
+     *   [user2.z32(), "100"],
+     * ];
+     * const stream = await pubky.eventStreamFor(homeserver)
+     *   .addUsers(users)
+     *   .live()
+     *   .subscribe();
+     * ```
+     */
+    addUsers(users: Array<any>): EventStreamBuilder;
+    /**
+     * Set maximum number of events to receive before closing the connection.
+     *
+     * If omitted:
+     * - With `live=false`: sends all historical events, then closes
+     * - With `live=true`: sends all historical events, then enters live mode (infinite stream)
+     *
+     * @param {number} limit - Maximum number of events (1-65535)
+     * @returns {EventStreamBuilder} - Builder for chaining
+     */
+    limit(limit: number): EventStreamBuilder;
+    /**
+     * Enable live streaming mode.
+     *
+     * When called, the stream will:
+     * 1. First deliver all historical events (oldest first)
+     * 2. Then remain open to stream new events as they occur in real-time
+     *
+     * Without this flag (default): Stream only delivers historical events and closes.
+     *
+     * **Note**: Cannot be combined with `reverse()`.
+     *
+     * ## Cleanup
+     * To stop a live stream, use the reader's `cancel()` method:
+     * ```typescript
+     * const stream = await pubky.eventStreamForUser(user, null).live().subscribe();
+     * const reader = stream.getReader();
+     *
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (shouldStop) {
+     *     await reader.cancel(); // Closes the connection
+     *     break;
+     *   }
+     * }
+     * ```
+     *
+     * @returns {EventStreamBuilder} - Builder for chaining
+     */
+    live(): EventStreamBuilder;
+    /**
+     * Filter events by path prefix.
+     *
+     * Format: Path WITHOUT `pubky://` scheme or user pubkey (e.g., "/pub/files/" or "/pub/").
+     * Only events whose path starts with this prefix are returned.
+     *
+     * @param {string} path - Path prefix to filter by
+     * @returns {EventStreamBuilder} - Builder for chaining
+     */
+    path(path: string): EventStreamBuilder;
+    /**
+     * Return events in reverse chronological order (newest first).
+     *
+     * When called, events are delivered from newest to oldest, then the stream closes.
+     *
+     * Without this flag (default): Events are delivered oldest first.
+     *
+     * **Note**: Cannot be combined with `live()`.
+     *
+     * @returns {EventStreamBuilder} - Builder for chaining
+     */
+    reverse(): EventStreamBuilder;
+    /**
+     * Subscribe to the event stream.
+     *
+     * This performs the following steps:
+     * 1. Resolves the user's homeserver via DHT/PKDNS
+     * 2. Constructs the `/events-stream` URL with query parameters
+     * 3. Makes the HTTP request
+     * 4. Returns a Web ReadableStream of parsed events
+     *
+     * @returns {Promise<ReadableStream>} - A Web ReadableStream that yields Event objects
+     *
+     * @throws {PubkyError}
+     * - `{ name: "RequestError" }` if the homeserver cannot be resolved
+     * - `{ name: "ValidationError" }` if `live=true` and `reverse=true` (invalid combination)
+     * - Propagates HTTP request errors
+     *
+     * @example
+     * ```typescript
+     * const stream = await builder.subscribe();
+     * for await (const event of stream) {
+     *   console.log(`${event.eventType}: ${event.resource.path}`);
+     * }
+     * ```
+     */
+    subscribe(): Promise<ReadableStream>;
+}
+
 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;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableByteStreamController): Promise<any>;
+    start(controller: ReadableByteStreamController): void;
+    readonly autoAllocateChunkSize: number;
+    readonly type: ReadableStreamType;
 }
+
 export class IntoUnderlyingSink {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  write(chunk: any): Promise<any>;
-  close(): Promise<any>;
-  abort(reason: any): Promise<any>;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    abort(reason: any): Promise<any>;
+    close(): Promise<any>;
+    write(chunk: any): Promise<any>;
 }
+
 export class IntoUnderlyingSource {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  pull(controller: ReadableStreamDefaultController): Promise<any>;
-  cancel(): void;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableStreamDefaultController): Promise<any>;
 }
+
 export class Keypair {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Generate a random [Keypair]
-   */
-  static random(): Keypair;
-  /**
-   * Generate a [Keypair] from a 32-byte secret.
-   */
-  static fromSecret(secret: Uint8Array): Keypair;
-  /**
-   * Returns the secret of this keypair.
-   */
-  secret(): Uint8Array;
-  /**
-   * Create a recovery file for this keypair (encrypted with the given passphrase).
-   */
-  createRecoveryFile(passphrase: string): Uint8Array;
-  /**
-   * 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 `.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.toString();
-   */
-  readonly publicKey: PublicKey;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a recovery file for this keypair (encrypted with the given passphrase).
+     */
+    createRecoveryFile(passphrase: string): Uint8Array;
+    /**
+     * Decrypt a recovery file and return a Keypair (decrypted with the given passphrase).
+     */
+    static fromRecoveryFile(recovery_file: Uint8Array, passphrase: string): Keypair;
+    /**
+     * Generate a [Keypair] from a 32-byte secret.
+     */
+    static fromSecret(secret: Uint8Array): Keypair;
+    /**
+     * Generate a random [Keypair]
+     */
+    static random(): Keypair;
+    /**
+     * Returns the secret of this keypair.
+     */
+    secret(): Uint8Array;
+    /**
+     * Returns the [PublicKey] of this keypair.
+     *
+     * 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.toString();
+     */
+    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).
-   */
-  constructor();
-  /**
-   * PKDNS actor with publishing enabled (requires a keypair).
-   */
-  static fromKeypair(keypair: Keypair): Pkdns;
-  /**
-   * Resolve the homeserver for a given public key (read-only).
-   *
-   * @param {PublicKey} user
-   * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
-   */
-  getHomeserverOf(pubky: PublicKey): Promise<PublicKey | undefined>;
-  /**
-   * Resolve the homeserver for **this** user (requires keypair).
-   *
-   * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
-   */
-  getHomeserver(): Promise<PublicKey | undefined>;
-  /**
-   * Force publish homeserver immediately (even if fresh).
-   *
-   * Requires keypair or to be signer bound.
-   *
-   * @param {PublicKey=} overrideHost Optional new homeserver to publish (migration).
-   * @returns {Promise<void>}
-   */
-  publishHomeserverForce(host_override?: PublicKey | null): Promise<void>;
-  /**
-   * Republish homeserver if record is missing/stale.
-   *
-   * Requires keypair or to be signer bound.
-   *
-   * @param {PublicKey=} overrideHost Optional new homeserver to publish (migration).
-   * @returns {Promise<void>}
-   */
-  publishHomeserverIfStale(host_override?: PublicKey | null): Promise<void>;
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * PKDNS actor with publishing enabled (requires a keypair).
+     */
+    static fromKeypair(keypair: Keypair): Pkdns;
+    /**
+     * Resolve the homeserver for **this** user (requires keypair).
+     *
+     * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
+     */
+    getHomeserver(): Promise<PublicKey | undefined>;
+    /**
+     * Resolve the homeserver for a given public key (read-only).
+     *
+     * @param {PublicKey} user
+     * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
+     */
+    getHomeserverOf(pubky: PublicKey): Promise<PublicKey | undefined>;
+    /**
+     * Read-only PKDNS actor (no keypair; resolve only).
+     */
+    constructor();
+    /**
+     * Force publish homeserver immediately (even if fresh).
+     *
+     * Requires keypair or to be signer bound.
+     *
+     * @param {PublicKey=} overrideHost Optional new homeserver to publish (migration).
+     * @returns {Promise<void>}
+     */
+    publishHomeserverForce(host_override?: PublicKey | null): Promise<void>;
+    /**
+     * Republish homeserver if record is missing/stale.
+     *
+     * Requires keypair or to be signer bound.
+     *
+     * @param {PublicKey=} overrideHost Optional new homeserver to publish (migration).
+     * @returns {Promise<void>}
+     */
+    publishHomeserverIfStale(host_override?: PublicKey | null): Promise<void>;
 }
+
 /**
  * High-level entrypoint to the Pubky SDK.
  */
 export class Pubky {
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * 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.
-   *
-   * @example
-   * const pubky = new Pubky();
-   * const signer = pubky.signer(Keypair.random());
-   */
-  constructor();
-  /**
-   * 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`).
-   *
-   * @param {string=} host Optional host (e.g. `"localhost"`, `"docker-host"`, `"127.0.0.1"`).
-   * @returns {Pubky}
-   *
-   * @example
-   * const pubky = Pubky.testnet();              // localhost default
-   * const pubky = Pubky.testnet("docker-host"); // custom hostname/IP
-   */
-  static testnet(host?: string | null): Pubky;
-  /**
-   * Wrap an existing configured HTTP client into a Pubky facade.
-   *
-   * @param {Client} client A previously constructed client.
-   * @returns {Pubky}
-   *
-   * @example
-   * const client = Client.testnet();
-   * const pubky = Pubky.withClient(client);
-   */
-  static withClient(client: Client): Pubky;
-  /**
-   * Start a **pubkyauth** flow.
-   *
-   * 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.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. Show `authorizationUrl` as QR/deeplink,
-   * then `awaitApproval()` to obtain a `Session`.
-   *
-   * @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-cool-app/:rw");
-   * renderQr(flow.authorizationUrl);
-   * const session = await flow.awaitApproval();
-   */
-  startAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
-  /**
-   * Create a `Signer` from an existing `Keypair`.
-   *
-   * @param {Keypair} keypair The user’s keys.
-   * @returns {Signer}
-   *
-   * @example
-   * const signer = pubky.signer(Keypair.random());
-   * 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 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 restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
-   */
-  restoreSession(exported: string): Promise<Session>;
-  /**
-   * Public, unauthenticated storage API.
-   *
-   * Use for **read-only** public access via addressed paths:
-   * `"pubky<user>/pub/…"`.
-   *
-   * @returns {PublicStorage}
-   *
-   * @example
-   * const text = await pubky.publicStorage.getText(`${userPk.toString()}/pub/example.com/hello.txt`);
-   */
-  readonly publicStorage: PublicStorage;
-  /**
-   * Access the underlying HTTP client (advanced).
-   *
-   * @returns {Client}
-   * Use this for low-level `fetch()` calls or testing with raw URLs.
-   *
-   * @example
-   * const r = await pubky.client.fetch(`pubky://${userPk.z32()}/pub/app/file.txt`, { credentials: "include" });
-   */
-  readonly client: Client;
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create an event stream builder for a specific homeserver.
+     *
+     * Use this when you already know the homeserver pubkey. This avoids
+     * Pkarr resolution overhead. Obtain a homeserver pubkey via `getHomeserverOf()`.
+     *
+     * @param {PublicKey} homeserver - The homeserver public key
+     * @returns {EventStreamBuilder} - Builder for configuring and subscribing to the stream
+     *
+     * @example
+     * ```typescript
+     * const homeserver = await pubky.getHomeserverOf(user1);
+     * const stream = await pubky.eventStreamFor(homeserver)
+     *   .addUsers([[user1.z32(), null], [user2.z32(), null]])
+     *   .live()
+     *   .subscribe();
+     *
+     * for await (const event of stream) {
+     *   console.log(`${event.eventType}: ${event.resource.path}`);
+     * }
+     * ```
+     */
+    eventStreamFor(homeserver: PublicKey): EventStreamBuilder;
+    /**
+     * Create an event stream builder for a single user.
+     *
+     * This is the simplest way to subscribe to events for one user. The homeserver
+     * is automatically resolved from the user's Pkarr record.
+     *
+     * @param {PublicKey} user - The user's public key
+     * @param {string | null} cursor - Optional cursor position to start from
+     * @returns {EventStreamBuilder} - Builder for configuring and subscribing to the stream
+     *
+     * @example
+     * ```typescript
+     * const user = PublicKey.from("o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo");
+     * const stream = await pubky.eventStreamForUser(user, null)
+     *   .live()
+     *   .subscribe();
+     *
+     * for await (const event of stream) {
+     *   console.log(`${event.eventType}: ${event.resource.path}`);
+     * }
+     * ```
+     */
+    eventStreamForUser(user: PublicKey, cursor?: string | null): EventStreamBuilder;
+    /**
+     * 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 or `undefined` if not found.
+     */
+    getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>;
+    /**
+     * 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.
+     *
+     * @example
+     * const pubky = new Pubky();
+     * const signer = pubky.signer(Keypair.random());
+     */
+    constructor();
+    /**
+     * 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 restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
+     */
+    restoreSession(exported: string): Promise<Session>;
+    /**
+     * Resume a previously started **pubkyauth** flow from its saved `authorizationUrl`.
+     *
+     * The relay inbox retains messages for **~5 minutes**. Resume is only
+     * viable within that window; afterwards start a fresh flow.
+     *
+     * **Security:** The URL contains the `client_secret` in plaintext.
+     * Delete it from storage as soon as the resumed flow completes.
+     * See `startAuthFlow()` docs for full storage guidance.
+     *
+     * @param {string} authorizationUrl The `pubkyauth://…` URL from a previous flow.
+     * @returns {AuthFlow} A flow reconnected to the original relay channel.
+     * @throws {PubkyError}
+     * - `{ name: "AuthenticationError" }` if the URL is invalid or not a signin/signup link
+     * - `{ name: "RequestError" }` on network/relay failure
+     */
+    resumeAuthFlow(authorization_url: string): AuthFlow;
+    /**
+     * Create a `Signer` from an existing `Keypair`.
+     *
+     * @param {Keypair} keypair The user’s keys.
+     * @returns {Signer}
+     *
+     * @example
+     * const signer = pubky.signer(Keypair.random());
+     * const session = await signer.signup(homeserverPk, null);
+     */
+    signer(keypair: Keypair): Signer;
+    /**
+     * Start a **pubkyauth** flow.
+     *
+     * 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.com/`).
+     * - `actions` is any combo of `r` and/or `w` (order normalized; `wr` -> `rw`).
+     * Pass `""` for no scopes (read-only public session).
+     *
+     * **Security:** `authorizationUrl` contains the `client_secret` in plaintext.
+     * If you need resume after refresh/app switch, save it in `sessionStorage`
+     * (not `localStorage`), then delete it once approval arrives or is abandoned.
+     *
+     * @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://…/inbox/"`).
+     * @returns {AuthFlow}
+     * A running auth flow. Show `authorizationUrl` as QR/deeplink,
+     * then `awaitApproval()` to obtain a `Session`.
+     *
+     * @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-cool-app/:rw");
+     * renderQr(flow.authorizationUrl);
+     * const session = await flow.awaitApproval();
+     */
+    startAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
+    /**
+     * 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`).
+     *
+     * @param {string=} host Optional host (e.g. `"localhost"`, `"docker-host"`, `"127.0.0.1"`).
+     * @returns {Pubky}
+     *
+     * @example
+     * const pubky = Pubky.testnet();              // localhost default
+     * const pubky = Pubky.testnet("docker-host"); // custom hostname/IP
+     */
+    static testnet(host?: string | null): Pubky;
+    /**
+     * Wrap an existing configured HTTP client into a Pubky facade.
+     *
+     * @param {Client} client A previously constructed client.
+     * @returns {Pubky}
+     *
+     * @example
+     * const client = Client.testnet();
+     * const pubky = Pubky.withClient(client);
+     */
+    static withClient(client: Client): Pubky;
+    /**
+     * Access the underlying HTTP client (advanced).
+     *
+     * @returns {Client}
+     * Use this for low-level `fetch()` calls or testing with raw URLs.
+     *
+     * @example
+     * const r = await pubky.client.fetch(`pubky://${userPk.z32()}/pub/app/file.txt`, { credentials: "include" });
+     */
+    readonly client: Client;
+    /**
+     * Public, unauthenticated storage API.
+     *
+     * Use for **read-only** public access via addressed paths:
+     * `"pubky<user>/pub/…"`.
+     *
+     * @returns {PublicStorage}
+     *
+     * @example
+     * const text = await pubky.publicStorage.getText(`${userPk.toString()}/pub/example.com/hello.txt`);
+     */
+    readonly publicStorage: PublicStorage;
+}
+
+/**
+ * An addressed resource: a user's public key paired with an absolute path.
+ *
+ * This represents a specific file or directory on a user's homeserver.
+ *
+ * @example
+ * ```typescript
+ * // Parse from a pubky URL
+ * const resource = PubkyResource.parse("pubky://o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo/pub/example.txt");
+ * console.log(resource.owner.z32()); // The user's public key
+ * console.log(resource.path);        // "/pub/example.txt"
+ * console.log(resource.toPubkyUrl()); // "pubky://o1gg96.../pub/example.txt"
+ * ```
+ */
+export class PubkyResource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Parse a pubky resource from a string.
+     *
+     * Accepts:
+     * - `pubky://<public_key>/<path>` (URL form)
+     * - `pubky<public_key>/<path>` (identifier form)
+     *
+     * @param {string} value - The resource string to parse
+     * @returns {PubkyResource} - The parsed resource
+     * @throws {Error} - If the string is not a valid pubky resource
+     */
+    static parse(value: string): PubkyResource;
+    /**
+     * Render as `pubky://<owner>/<path>` (deep-link/URL form).
+     */
+    toPubkyUrl(): string;
+    /**
+     * Render as `pubky<owner>/<path>` (identifier form).
+     */
+    toString(): string;
+    /**
+     * Get the owner's public key.
+     */
+    readonly owner: PublicKey;
+    /**
+     * Get the absolute path (e.g., "/pub/example.txt").
+     */
+    readonly path: string;
 }
+
 export class PublicKey {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Convert the PublicKey to Uint8Array
-   */
-  toUint8Array(): Uint8Array;
-  /**
-   * 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;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * @throws
+     */
+    static from(value: string): PublicKey;
+    /**
+     * Returns the identifier form with the `pubky` prefix.
+     * Use for display only; transport/storage should use `.z32()`.
+     */
+    toString(): string;
+    /**
+     * Convert the PublicKey to Uint8Array
+     */
+    toUint8Array(): Uint8Array;
+    /**
+     * Returns the z-base32 encoding of this public key
+     */
+    z32(): string;
 }
+
 /**
  * Read-only public storage using addressed paths (`"pubky<user>/pub/..."`).
  */
 export class PublicStorage {
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Construct PublicStorage using global client (mainline relays).
-   */
-  constructor();
-  /**
-   * List a directory. Results are `pubky://…` identifier URLs.
-   *
-   * @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: 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 {Address} address
-   * @returns {Promise<Uint8Array>}
-   */
-  getBytes(address: Address): Promise<Uint8Array>;
-  /**
-   * Fetch text from an addressed path as UTF-8 text.
-   *
-   * @param {Address} address
-   * @returns {Promise<string>}
-   */
-  getText(address: Address): Promise<string>;
-  /**
-   * Fetch JSON from an addressed path.
-   *
-   * @param {Address} address `"pubky<user>/pub/.../file.json"` (preferred) or `pubky://<user>/pub/...`.
-   * @returns {Promise<any>}
-   */
-  getJson(address: Address): Promise<any>;
-  /**
-   * Check if a path exists.
-   *
-   * @param {Address} address
-   * @returns {Promise<boolean>}
-   */
-  exists(address: Address): Promise<boolean>;
-  /**
-   * Get metadata for an address
-   *
-   * @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 {PubkyError} On invalid input or transport/server errors.
-   */
-  stats(address: Address): Promise<ResourceStats | undefined>;
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Check if a path exists.
+     *
+     * @param {Address} address
+     * @returns {Promise<boolean>}
+     */
+    exists(address: Address): Promise<boolean>;
+    /**
+     * 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 {Address} address
+     * @returns {Promise<Uint8Array>}
+     */
+    getBytes(address: Address): Promise<Uint8Array>;
+    /**
+     * Fetch JSON from an addressed path.
+     *
+     * @param {Address} address `"pubky<user>/pub/.../file.json"` (preferred) or `pubky://<user>/pub/...`.
+     * @returns {Promise<any>}
+     */
+    getJson(address: Address): Promise<any>;
+    /**
+     * Fetch text from an addressed path as UTF-8 text.
+     *
+     * @param {Address} address
+     * @returns {Promise<string>}
+     */
+    getText(address: Address): Promise<string>;
+    /**
+     * List a directory. Results are `pubky://…` identifier URLs.
+     *
+     * @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: Address, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+    /**
+     * Construct PublicStorage using global client (mainline relays).
+     */
+    constructor();
+    /**
+     * Get metadata for an address
+     *
+     * @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 {PubkyError} On invalid input or transport/server errors.
+     */
+    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;
+    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`)
  * - 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}
-   */
-  readonly info: SessionInfo;
-  /**
-   * Access the session-scoped storage API (read/write).
-   *
-   * @returns {SessionStorage}
-   */
-  readonly storage: SessionStorage;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): 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>;
+    /**
+     * 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}
+     */
+    readonly info: SessionInfo;
+    /**
+     * Access the session-scoped storage API (read/write).
+     *
+     * @returns {SessionStorage}
+     */
+    readonly storage: SessionStorage;
 }
+
 /**
  * Static snapshot of session metadata.
  */
 export class SessionInfo {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * The user’s public key for this session.
-   *
-   * 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.toString();
-   */
-  readonly publicKey: PublicKey;
-  /**
-   * Effective capabilities granted to this session.
-   *
-   * @returns {string[]} Normalized capability entries (e.g. `"/pub/app/:rw"`).
-   */
-  readonly capabilities: string[];
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Effective capabilities granted to this session.
+     *
+     * @returns {string[]} Normalized capability entries (e.g. `"/pub/app/:rw"`).
+     */
+    readonly capabilities: string[];
+    /**
+     * The user’s public key for this session.
+     *
+     * 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.toString();
+     */
+    readonly publicKey: PublicKey;
 }
+
 /**
  * Read/write storage scoped to **your** session (absolute paths: `/pub/...`).
  */
 export class SessionStorage {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * List a directory (absolute session path). Returns `pubky://…` URLs.
-   *
-   * @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: 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 {Path} path
-   * @returns {Promise<Uint8Array>}
-   */
-  getBytes(path: Path): Promise<Uint8Array>;
-  /**
-   * GET text from an absolute session path.
-   *
-   * @param {Path} path
-   * @returns {Promise<string>}
-   */
-  getText(path: Path): Promise<string>;
-  /**
-   * GET JSON from an absolute session path.
-   *
-   * @param {Path} path
-   * @returns {Promise<any>}
-   */
-  getJson(path: Path): Promise<any>;
-  /**
-   * Check existence.
-   *
-   * @param {Path} path
-   * @returns {Promise<boolean>}
-   */
-  exists(path: Path): Promise<boolean>;
-  /**
-   * Get metadata for an absolute, session-scoped path (e.g. `"/pub/app/file.json"`).
-   *
-   * @param {Path} path Absolute path under your user (starts with `/`).
-   * @returns {Promise<ResourceStats|undefined>} `undefined` if the resource does not exist.
-   * @throws {PubkyError} On invalid input or transport/server errors.
-   */
-  stats(path: Path): Promise<ResourceStats | undefined>;
-  /**
-   * PUT binary at an absolute session path.
-   *
-   * @param {Path} path
-   * @param {Uint8Array} bytes
-   * @returns {Promise<void>}
-   */
-  putBytes(path: Path, body: Uint8Array): Promise<void>;
-  /**
-   * PUT text at an absolute session path.
-   *
-   * @param {Path} path
-   * @param {string} text
-   * @returns {Promise<void>}
-   */
-  putText(path: Path, body: string): Promise<void>;
-  /**
-   * PUT JSON at an absolute session path.
-   *
-   * @param {Path} path Absolute path (e.g. `"/pub/app/data.json"`).
-   * @param {any} value JSON-serializable value.
-   * @returns {Promise<void>}
-   */
-  putJson(path: Path, body: any): Promise<void>;
-  /**
-   * Delete a path (file or empty directory).
-   *
-   * @param {Path} path
-   * @returns {Promise<void>}
-   */
-  delete(path: Path): Promise<void>;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Delete a path (file or empty directory).
+     *
+     * @param {Path} path
+     * @returns {Promise<void>}
+     */
+    delete(path: Path): Promise<void>;
+    /**
+     * Check existence.
+     *
+     * @param {Path} path
+     * @returns {Promise<boolean>}
+     */
+    exists(path: Path): Promise<boolean>;
+    /**
+     * 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 {Path} path
+     * @returns {Promise<Uint8Array>}
+     */
+    getBytes(path: Path): Promise<Uint8Array>;
+    /**
+     * GET JSON from an absolute session path.
+     *
+     * @param {Path} path
+     * @returns {Promise<any>}
+     */
+    getJson(path: Path): Promise<any>;
+    /**
+     * GET text from an absolute session path.
+     *
+     * @param {Path} path
+     * @returns {Promise<string>}
+     */
+    getText(path: Path): Promise<string>;
+    /**
+     * List a directory (absolute session path). Returns `pubky://…` URLs.
+     *
+     * @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: Path, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+    /**
+     * PUT binary at an absolute session path.
+     *
+     * @param {Path} path
+     * @param {Uint8Array} bytes
+     * @returns {Promise<void>}
+     */
+    putBytes(path: Path, body: Uint8Array): Promise<void>;
+    /**
+     * PUT JSON at an absolute session path.
+     *
+     * @param {Path} path Absolute path (e.g. `"/pub/app/data.json"`).
+     * @param {any} value JSON-serializable value.
+     * @returns {Promise<void>}
+     */
+    putJson(path: Path, body: any): Promise<void>;
+    /**
+     * PUT text at an absolute session path.
+     *
+     * @param {Path} path
+     * @param {string} text
+     * @returns {Promise<void>}
+     */
+    putText(path: Path, body: string): Promise<void>;
+    /**
+     * Get metadata for an absolute, session-scoped path (e.g. `"/pub/app/file.json"`).
+     *
+     * @param {Path} path Absolute path under your user (starts with `/`).
+     * @returns {Promise<ResourceStats|undefined>} `undefined` if the resource does not exist.
+     * @throws {PubkyError} On invalid input or transport/server errors.
+     */
+    stats(path: Path): Promise<ResourceStats | undefined>;
 }
+
 /**
  * Holds a user’s `Keypair` and performs identity operations:
  * - `signup` creates a new homeserver user.
@@ -978,87 +1268,133 @@ export class SessionStorage {
  * - Publish PKDNS when signer-bound
  */
 export class Signer {
-  private constructor();
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Create a signer from a `Keypair` (prefer `pubky.signer(kp)`).
-   *
-   * @param {Keypair} keypair
-   * @returns {Signer}
-   */
-  static fromKeypair(keypair: Keypair): Signer;
-  /**
-   * Sign up at a homeserver. Returns a ready `Session`.
-   *
-   * Creates a valid homeserver Session with root capabilities
-   *
-   * @param {PublicKey} homeserver The homeserver’s public key.
-   * @param {string|null} signupToken Invite/registration token or `null`.
-   * @returns {Promise<Session>}
-   *
-   * @throws {PubkyError}
-   * - `AuthenticationError` (bad/expired token)
-   * - `RequestError` (network/server)
-   */
-  signup(homeserver: PublicKey, signup_token?: string | null): Promise<Session>;
-  /**
-   * Fast sign-in for a returning user. Publishes PKDNS in the background.
-   *
-   * Creates a valid homeserver Session with root capabilities
-   *
-   * @returns {Promise<Session>}
-   *
-   * @throws {PubkyError}
-   */
-  signin(): Promise<Session>;
-  /**
-   * Blocking sign-in. Waits for PKDNS publish to complete (slower; safer).
-   *
-   * Creates a valid homeserver Session with root capabilities
-   *
-   * @returns {Promise<Session>}
-   */
-  signinBlocking(): Promise<Session>;
-  /**
-   * 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);
-   */
-  readonly pkdns: Pkdns;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Approve a `pubkyauth://` request URL (encrypts & POSTs the signed AuthToken).
+     */
+    approveAuthRequest(pubkyauth_url: string): Promise<void>;
+    /**
+     * Create a signer from a `Keypair` (prefer `pubky.signer(kp)`).
+     *
+     * @param {Keypair} keypair
+     * @returns {Signer}
+     */
+    static fromKeypair(keypair: Keypair): Signer;
+    /**
+     * Fast sign-in for a returning user. Publishes PKDNS in the background.
+     *
+     * Creates a valid homeserver Session with root capabilities
+     *
+     * @returns {Promise<Session>}
+     *
+     * @throws {PubkyError}
+     */
+    signin(): Promise<Session>;
+    /**
+     * Blocking sign-in. Waits for PKDNS publish to complete (slower; safer).
+     *
+     * Creates a valid homeserver Session with root capabilities
+     *
+     * @returns {Promise<Session>}
+     */
+    signinBlocking(): Promise<Session>;
+    /**
+     * Sign up at a homeserver. Returns a ready `Session`.
+     *
+     * Creates a valid homeserver Session with root capabilities
+     *
+     * @param {PublicKey} homeserver The homeserver’s public key.
+     * @param {string|null} signupToken Invite/registration token or `null`.
+     * @returns {Promise<Session>}
+     *
+     * @throws {PubkyError}
+     * - `AuthenticationError` (bad/expired token)
+     * - `RequestError` (network/server)
+     */
+    signup(homeserver: PublicKey, signup_token?: string | null): Promise<Session>;
+    /**
+     * Get a PKDNS actor bound to this signer's client & keypair (publishing enabled).
+     *
+     * @returns {Pkdns}
+     *
+     * @example
+     * await signer.pkdns.publishHomeserverIfStale(homeserverPk);
+     */
+    readonly pkdns: Pkdns;
+    /**
+     * Get the public key of this signer.
+     *
+     * @returns {PublicKey}
+     */
+    readonly publicKey: PublicKey;
 }
+
 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;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    static parse(url: string): SigninDeepLink;
+    toString(): string;
+    readonly baseRelayUrl: string;
+    readonly capabilities: 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;
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    static parse(url: string): SignupDeepLink;
+    toString(): string;
+    readonly baseRelayUrl: string;
+    readonly capabilities: string;
+    readonly homeserver: PublicKey;
+    readonly secret: Uint8Array;
+    readonly signupToken: string | undefined;
 }
+
+/**
+ * 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;
+
+/**
+ * Set the global logging verbosity for the WASM Pubky SDK. Routes Rust `log` output to the browser console.
+ *
+ * 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 {Level} level
+ *        Minimum log level to enable. One of: "error" | "warn" | "info" | "debug" | "trace".
+ *
+ * @returns {void}
+ *
+ * @throws {Error}
+ *         If `level` is invalid ("Invalid log level") or the logger cannot be initialized
+ *         (e.g., already initialized).
+ *
+ * Usage:
+ *   Call once at application startup, before invoking other SDK APIs.
+ */
+export function setLogLevel(level: Level): void;
+
+/**
+ * Validate and normalize a capabilities string.
+ *
+ * - Normalizes action order (`wr` -> `rw`)
+ * - Throws `InvalidInput` listing malformed entries.
+ *
+ * @param {string} input
+ * @returns {string} Normalized string (same shape as input).
+ * @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;