@synonymdev/pubky 0.5.4 → 0.6.0-rc.6

package/pubky.d.ts

@@ -1,16 +1,175 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
- * Create a recovery file of the `keypair`, containing the secret key encrypted
- * using the `passphrase`.
+ * 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 createRecoveryFile(keypair: Keypair, passphrase: string): Uint8Array;
+export function setLogLevel(level: Level): void;
 /**
- * Create a recovery file of the `keypair`, containing the secret key encrypted
- * using the `passphrase`.
+ * 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 decryptRecoveryFile(recovery_file: Uint8Array, passphrase: string): Keypair;
-export function setLogLevel(level: string): void;
+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";
+/**
+ * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
+ *
+ * @typedef {Object} ResourceStats
+ * @property {number=} contentLength  Size in bytes.
+ * @property {string=} contentType    Media type (e.g. \"application/json; charset=utf-8\").
+ * @property {number=} lastModifiedMs Unix epoch milliseconds.
+ * @property {string=} etag           Opaque server ETag for the current version.
+ *
+ * @example
+ * const stats = await pubky.publicStorage.stats(`${user}/pub/app/file.json`);
+ * if (stats) {
+ *   console.log(stats.contentLength, stats.contentType, stats.lastModifiedMs);
+ * }
+ *
+ * Notes:
+ * - `contentLength` equals `getBytes(...).length`.
+ * - `etag` may be absent and is opaque; compare values to detect updates.
+ * - `lastModifiedMs` increases when the resource is updated.
+ */
+export interface ResourceStats {
+    /**
+     * Size in bytes of the stored object.
+     */
+    contentLength?: number;
+    /**
+     * Media type of the stored object (e.g., `\"application/json\"`).
+     */
+    contentType?: string;
+    /**
+     * Unix epoch **milliseconds** for the last modification time.
+     */
+    lastModifiedMs?: number;
+    /**
+     * Opaque entity tag identifying the current stored version.
+     */
+    etag?: string;
+}
+
+export type Path = `/pub/${string}`;
+
+/**
+ * A union type of all possible machine-readable codes for the `name` property
+ * of a {@link PubkyError}.
+ *
+ * Provides a simplified, actionable set of error categories for developers
+ * to handle in their code.
+ */
+export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationError" | "PkarrError" | "ClientStateError" | "InternalError";
+
+/**
+ * Represents the standard error structure for all exceptions thrown by the Pubky
+ * WASM client.
+ *
+ * @property name - A machine-readable error code from {@link PubkyErrorName}. Use this for programmatic error handling.
+ * @property message - A human-readable, descriptive error message suitable for logging.
+ * @property data - An optional payload containing structured context for an error. For a `RequestError`, this may contain an object with the HTTP status code, e.g., `{ statusCode: 404 }`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.signup(...);
+ * } catch (e) {
+ *   const error = e as PubkyError;
+ *   if (
+ *     error.name === \'RequestError\' &&
+ *     typeof error.data === \'object\' &&
+ *     error.data !== null &&
+ *     \'statusCode\' in error.data &&
+ *     (error.data as { statusCode?: number }).statusCode === 404
+ *   ) {
+ *     // Handle not found...
+ *   }
+ * }
+ * ```
+ */
+export interface PubkyError {
+    name: PubkyErrorName;
+    message: string;
+    /**
+     * Optional structured context associated with the error.
+     */
+    data?: unknown;
+}
+
+/**
+ * Represents the standard error structure for all exceptions thrown by the Pubky
+ * WASM client.
+ *
+ * @property name - A machine-readable error code from {@link PubkyErrorName}. Use this for programmatic error handling.
+ * @property message - A human-readable, descriptive error message suitable for logging.
+ * @property data - An optional payload containing structured context for an error. For a `RequestError`, this may contain an object with the HTTP status code, e.g., `{ statusCode: 404 }`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.signup(...);
+ * } catch (e) {
+ *   const error = e as PubkyError;
+ *   if (
+ *     error.name === "RequestError" &&
+ *     typeof error.data === "object" &&
+ *     error.data !== null &&
+ *     "statusCode" in error.data &&
+ *     (error.data as { statusCode?: number }).statusCode === 404
+ *   ) {
+ *     // Handle not found...
+ *   }
+ * }
+ * ```
+ */
+export interface PubkyError extends Error {
+  name: PubkyErrorName;
+  message: string;
+  data?: unknown;
+}
+
+export type Address = `pubky${string}/pub/${string}` | `pubky://${string}/pub/${string}`;
+
 /**
  * Pkarr Config
  */
@@ -23,7 +182,7 @@ export interface PkarrConfig {
      * The timeout for DHT requests in milliseconds.
      * Default is 2000ms.
      */
-    requestTimeout?: NonZeroU64;
+    requestTimeout?: number;
 }
 
 /**
@@ -34,114 +193,261 @@ export interface PubkyClientConfig {
      * Configuration on how to access pkarr packets on the mainline DHT.
      */
     pkarr?: PkarrConfig;
-    /**
-     * The maximum age of a record in seconds.
-     * If the user pkarr record is older than this, it will be automatically refreshed.
-     */
-    userMaxRecordAge?: NonZeroU64;
 }
 
-export class AuthRequest {
+export type CapabilityAction = "r" | "w" | "rw";
+export type CapabilityScope = `/${string}`;
+export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
+type CapabilitiesTail = `,${CapabilityEntry}${string}`;
+export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
+
+/**
+ * Start and control a pubkyauth authorization flow.
+ *
+ * Typical flow:
+ * 1) `AuthFlow.start(...)` or `pubky.startAuthFlow(...)`
+ * 2) Show `authorizationUrl()` as QR/deeplink to the user’s signing device
+ * 3) `awaitApproval()` to receive a ready `Session`
+ */
+export class AuthFlow {
   private constructor();
   free(): void;
   /**
-   * Returns the Pubky Auth url, which you should show to the user
-   * to request an authentication or authorization token.
+   * 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.app/`)
+   * - `actions` is any combo of `r` and/or `w` (order is normalized; `wr` -> `rw`)
+   * Empty string is allowed (no scopes).
    *
-   * Wait for this token using `this.response()`.
+   * @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.app/:rw,/pub/pubky.app/:w");
+   * renderQRCode(flow.authorizationUrl());
+   * const session = await flow.awaitApproval();
    */
-  url(): string;
+  static start(capabilities: Capabilities, relay?: string | null): AuthFlow;
   /**
-   * Wait for the user to send an authentication or authorization proof.
+   * Block until the user approves on their signer device; returns a `Session`.
    *
-   * If successful, you should expect an instance of [PublicKey]
+   * @returns {Promise<Session>}
+   * Resolves when approved; rejects on timeout/cancel/network errors.
    *
-   * Otherwise it will throw an error.
+   * @throws {PubkyError}
+   * - `RequestError` if relay/network fails
+   * - `AuthenticationError` if approval is denied/invalid
    */
-  response(): Promise<PublicKey>;
-}
-export class Client {
-  free(): void;
+  awaitApproval(): Promise<Session>;
   /**
-   * Signup to a homeserver and update Pkarr accordingly.
+   * Block until the user approves on their signer device; returns an `AuthToken`.
    *
-   * The homeserver is a Pkarr domain name, where the TLD is a Pkarr public key
-   * for example "pubky.o4dksfbqk85ogzdb5osziw6befigbuxmuxkuxq8434q89uj56uyy"
+   * @returns {Promise<AuthToken>}
+   * Resolves when approved; rejects on timeout/cancel/network errors.
+   *
+   * @throws {PubkyError}
+   * - `RequestError` if relay/network fails
    */
-  signup(keypair: Keypair, homeserver: PublicKey, signup_token?: string | null): Promise<Session>;
+  awaitToken(): Promise<AuthToken>;
   /**
-   * Check the current session for a given Pubky in its homeserver.
+   * Non-blocking single poll step (advanced UIs).
    *
-   * Returns [Session] or `None` (if received `404 NOT_FOUND`),
-   * or throws the received error if the response has any other `>=400` status code.
+   * @returns {Promise<Session|undefined>} A session if the approval arrived, otherwise `undefined`.
    */
-  session(pubky: PublicKey): Promise<Session | undefined>;
+  tryPollOnce(): Promise<Session | undefined>;
   /**
-   * Signout from a homeserver.
+   * 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());
    */
-  signout(pubky: PublicKey): Promise<void>;
+  readonly authorizationUrl: string;
+}
+/**
+ * AuthToken: signed, time-bound proof of key ownership.
+ *
+ * Returned by [`AuthFlow.awaitToken()`] on the 3rd-party app side when doing **authentication-only**
+ * flows (no homeserver session). You can inspect who authenticated and which capabilities were
+ * requested, or serialize the token and send it to a backend to verify.
+ *
+ * ### Typical usage
+ * ```js
+ * // Start an auth-only flow (no capabilities)
+ * const flow = pubky.startAuthFlow("", relay);
+ *
+ * // Wait for the signer to approve; returns an AuthToken
+ * const token = await flow.awaitToken();
+ *
+ * // Identify the user
+ * console.log(token.publicKey().z32());
+ *
+ * // Optionally forward to a server for verification:
+ * await fetch("/api/verify", { method: "POST", body: token.toBytes() });
+ * ```
+ *
+ * ### Binary format
+ * `AuthToken` serializes to a canonical binary (postcard) form; use [`AuthToken.toBytes()`] to get a
+ * `Uint8Array`, and [`AuthToken.verify()`] to parse + verify on the server.
+ */
+export class AuthToken {
+  private constructor();
+  free(): void;
   /**
-   * Signin to a homeserver using the root Keypair.
+   * 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().z32(), { status: 200 });
+   * }
+   * ```
    */
-  signin(keypair: Keypair): Promise<void>;
+  static verify(bytes: Uint8Array): AuthToken;
   /**
-   * Return `pubkyauth://` url and wait for the incoming [AuthToken]
-   * verifying that AuthToken, and if capabilities were requested, signing in to
-   * the Pubky's homeserver and returning the [Session] information.
+   * 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.
    *
-   * Returns a [AuthRequest]
+   * Throws if the bytes cannot be parsed as a valid serialized token.
    */
-  authRequest(relay: string, capabilities: string): AuthRequest;
+  static fromBytes(bytes: Uint8Array): AuthToken;
   /**
-   * Sign an [pubky_common::auth::AuthToken], encrypt it and send it to the
-   * source of the pubkyauth request url.
+   * 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 });
+   * ```
    */
-  sendAuthToken(keypair: Keypair, pubkyauth_url: string): Promise<void>;
+  toBytes(): Uint8Array;
   /**
-   * Get the homeserver id for a given Pubky public key.
-   * Looks up the pkarr packet for the given public key and returns the content of the first `_pubky` SVCB record.
-   * Throws an error if no homeserver is found.
+   * 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();
    */
-  getHomeserver(public_key: PublicKey): Promise<PublicKey>;
+  readonly publicKey: PublicKey;
   /**
-   * Republish the user's PKarr record pointing to their homeserver.
+   * Returns the **capabilities** requested by the flow at the time this token was signed.
    *
-   * This method will republish the record if no record exists or if the existing record
-   * is older than 6 hours.
+   * Most auth-only flows pass an empty string to `startAuthFlow("", relay)`, so this will
+   * commonly be an empty array.
    *
-   * The method is intended for clients and key managers (e.g., pubky-ring) to
-   * keep the records of active users fresh and available in the DHT and relays.
-   * It is intended to be used only after failed signin due to homeserver resolution
-   * failure. This method is lighter than performing a re-signup into the last known
-   * homeserver, but does not return a session token, so a signin must be done after
-   * republishing. On a failed signin due to homeserver resolution failure, a key
-   * manager should always attempt to republish the last known homeserver.
+   * Returns: `string[]`, where each item is the canonical entry `"<scope>:<actions>"`.
+   *
+   * Example entry: `"/pub/my.app/:rw"`
    */
-  republishHomeserver(keypair: Keypair, host: PublicKey): Promise<void>;
+  readonly capabilities: string[];
+}
+/**
+ * Low-level HTTP bridge used by the Pubky facade and actors.
+ *
+ * - Supports `http(s)://` URLs targeting Pubky or ICANN hosts.
+ * - In browsers/undici, passes `credentials: "include"` to send cookies.
+ */
+export class Client {
+  free(): void;
   /**
-   * Returns a list of Pubky urls (as strings).
+   * Perform a raw fetch. Works with `http(s)://` URLs.
    *
-   * - `url`:     The Pubky url (string) to the directory you want to list its content.
-   * - `cursor`:  Either a full `pubky://` Url (from previous list response),
-   *                 or a path (to a file or directory) relative to the `url`
-   * - `reverse`: List in reverse order
-   * - `limit`    Limit the number of urls in the response
-   * - `shallow`: List directories and files, instead of flat list of files.
+   * @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" });
    */
-  list(url: string, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<Array<any>>;
-  fetch(url: string, init?: any | null): Promise<Promise<any>>;
+  fetch(url: string, init?: RequestInit | null): Promise<Response>;
   /**
-   * Create a new Pubky Client with an optional configuration.
+   * 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 with with configurations appropriate for local testing:
-   * - set Pkarr relays to `http://<host>:15411` (defaults to `localhost`).
-   * - transform `pubky://<pkarr public key>` to `http://<host>` instead of `https:`
-   *   and read the homeserver HTTP port from the PKarr record.
+   * 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;
 }
+export class IntoUnderlyingByteSource {
+  private constructor();
+  free(): void;
+  start(controller: ReadableByteStreamController): void;
+  pull(controller: ReadableByteStreamController): Promise<any>;
+  cancel(): void;
+  readonly type: ReadableStreamType;
+  readonly autoAllocateChunkSize: number;
+}
+export class IntoUnderlyingSink {
+  private constructor();
+  free(): void;
+  write(chunk: any): Promise<any>;
+  close(): Promise<any>;
+  abort(reason: any): Promise<any>;
+}
+export class IntoUnderlyingSource {
+  private constructor();
+  free(): void;
+  pull(controller: ReadableStreamDefaultController): Promise<any>;
+  cancel(): void;
+}
 export class Keypair {
   private constructor();
   free(): void;
@@ -157,19 +463,182 @@ export class Keypair {
    * Returns the secret key of this keypair.
    */
   secretKey(): 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 `.z32()` on the returned `PublicKey` to get the string form.
+   *
+   * @example
+   * const who = keypair.publicKey.z32();
    */
-  publicKey(): PublicKey;
+  readonly publicKey: PublicKey;
 }
-export class PublicKey {
-  private constructor();
+/**
+ * Resolve/publish `_pubky` PKDNS records (homeserver pointers).
+ */
+export class Pkdns {
   free(): void;
   /**
-   * Convert the PublicKey to Uint8Array
-   * @deprecated Use `toUint8Array` instead
+   * 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>;
+}
+/**
+ * High-level entrypoint to the Pubky SDK.
+ */
+export class Pubky {
+  free(): void;
+  /**
+   * Create a Pubky facade wired for **mainnet** defaults (public relays).
+   *
+   * @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.app/`).
+   * - `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 {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.app/:rw");
+   * renderQr(flow.authorizationUrl);
+   * const session = await flow.awaitApproval();
+   */
+  startAuthFlow(capabilities: Capabilities, 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);
    */
-  to_uint8array(): Uint8Array;
+  signer(keypair: Keypair): Signer;
+  /**
+   * Resolve the homeserver for a given public key (read-only).
+   *
+   * Uses an internal read-only Pkdns actor.
+   *
+   * @param {PublicKey} user
+   * @returns {Promise<PublicKey|undefined>} Homeserver public key (z32) or `undefined` if not found.
+   */
+  getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>;
+  /**
+   * Public, unauthenticated storage API.
+   *
+   * Use for **read-only** public access via addressed paths:
+   * `"<user-z32>/pub/…"`.
+   *
+   * @returns {PublicStorage}
+   *
+   * @example
+   * const text = await pubky.publicStorage.getText(`${userPk.z32()}/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://${user}/pub/app/file.txt`, { credentials: "include" });
+   */
+  readonly client: Client;
+}
+export class PublicKey {
+  private constructor();
+  free(): void;
   /**
    * Convert the PublicKey to Uint8Array
    */
@@ -183,15 +652,280 @@ export class PublicKey {
    */
   static from(value: string): PublicKey;
 }
+/**
+ * Read-only public storage using addressed paths (`"<user-z32>/pub/...")`.
+ */
+export class PublicStorage {
+  free(): 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>;
+}
+/**
+ * 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;
   /**
-   * Return the [PublicKey] of this 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;
+  /**
+   * 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();
+   */
+  readonly publicKey: PublicKey;
+  /**
+   * Effective capabilities granted to this session.
+   *
+   * @returns {string[]} Normalized capability entries (e.g. `"/pub/app/:rw"`).
+   */
+  readonly capabilities: string[];
+}
+/**
+ * Read/write storage scoped to **your** session (absolute paths: `/pub/...`).
+ */
+export class SessionStorage {
+  private constructor();
+  free(): 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>;
+}
+/**
+ * Holds a user’s `Keypair` and performs identity operations:
+ * - `signup` creates a new homeserver user.
+ * - `signin` creates a homeserver session for an existing user.
+ * - Approve pubkyauth requests
+ * - Publish PKDNS when signer-bound
+ */
+export class Signer {
+  private constructor();
+  free(): 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}
    */
-  pubky(): PublicKey;
+  signin(): Promise<Session>;
   /**
-   * Return the capabilities that this session has.
+   * 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);
    */
-  capabilities(): string[];
+  readonly pkdns: Pkdns;
 }