@synonymdev/pubky 0.5.2 → 0.6.0-rc.2

package/pubky.d.ts

@@ -0,0 +1,821 @@
+/* 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-insensitive): "error" | "warn" | "info" | "debug" | "trace".
+ * Effects:
+ * - Initializes the logger once; subsequent calls may throw if the logger is already set.
+ * - Emits a single info log: `Log level set to: <level>`.
+ * - Messages at or above `level` are forwarded to the appropriate `console.*` method.
+ *
+ * @param {string} level
+ *        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: string): 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 {PubkyJsError} `{ name: "InvalidInput" }` with a helpful message.
+ */
+export function validateCapabilities(input: string): string;
+/**
+ * A union type of all possible machine-readable codes for the `name` property
+ * of a {@link PubkyJsError}.
+ *
+ * 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 PubkyJsError;
+ *   if (error.name === \'RequestError\' && error.statusCode === 404) {
+ *     // Handle not found...
+ *   }
+ * }
+ * ```
+ */
+export interface PubkyJsError {
+    name: PubkyErrorName;
+    message: string;
+    /**
+     * For `RequestError::Server`, this carries the numeric HTTP status code (e.g. 404).
+     * Otherwise `undefined` on the JS side.
+     */
+    statusCode?: number;
+}
+
+/**
+ * Pkarr Config
+ */
+export interface PkarrConfig {
+    /**
+     * The list of relays to access the DHT with.
+     */
+    relays?: string[];
+    /**
+     * The timeout for DHT requests in milliseconds.
+     * Default is 2000ms.
+     */
+    requestTimeout?: number;
+}
+
+/**
+ * Pubky Client Config
+ */
+export interface PubkyClientConfig {
+    /**
+     * Configuration on how to access pkarr packets on the mainline DHT.
+     */
+    pkarr?: PkarrConfig;
+}
+
+/**
+ * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
+ *
+ * @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;
+}
+
+/**
+ * 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;
+  /**
+   * Start a flow (standalone).
+   * Prefer `pubky.startAuthFlow()` to reuse a façade 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).
+   *
+   * @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 {PubkyJsError}
+   * - `{ 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();
+   */
+  static start(capabilities: string, relay?: string | null): AuthFlow;
+  /**
+   * Return the authorization deep link (URL) to show as QR or open on the signer device.
+   *
+   * @returns {string} A `pubkyauth://…` or `https://…` URL with channel info.
+   *
+   * @example
+   * renderQr(flow.authorizationUrl());
+   */
+  authorizationUrl(): string;
+  /**
+   * Block until the user approves on their signer device; returns a `Session`.
+   *
+   * @returns {Promise<Session>}
+   * Resolves when approved; rejects on timeout/cancel/network errors.
+   *
+   * @throws {PubkyJsError}
+   * - `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 {PubkyJsError}
+   * - `RequestError` if relay/network fails
+   */
+  awaitToken(): Promise<AuthToken>;
+  /**
+   * Non-blocking single poll step (advanced UIs).
+   *
+   * @returns {Promise<Session|null>} A session if the approval arrived, otherwise `null`.
+   */
+  tryPollOnce(): Promise<Session | undefined>;
+}
+/**
+ * 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;
+  /**
+   * 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 });
+   * }
+   * ```
+   */
+  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;
+  /**
+   * Returns the **public key** that authenticated with this token.
+   *
+   * Use `.z32()` on the returned `PublicKey` to get the string form.
+   *
+   * ```js
+   * const who = token.publicKey().z32();
+   * ```
+   */
+  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.app/:rw"`
+   */
+  capabilities(): Array<any>;
+  /**
+   * Serialize the token to a `Uint8Array` in its **canonical** (postcard) binary format.
+   *
+   * Use this to send the token to a backend for verification.
+   *
+   * ```js
+   * const bytes = token.toBytes();
+   * await fetch("/api/verify", { method: "POST", body: bytes });
+   * ```
+   */
+  toBytes(): Uint8Array;
+}
+/**
+ * Low-level HTTP bridge used by the Pubky façade and actors.
+ *
+ * - Supports `pubky://<user-z32>/<abs-path>` and `http(s)://` URLs.
+ * - In browsers/undici, passes `credentials: "include"` to send cookies.
+ */
+export class Client {
+  free(): void;
+  /**
+   * 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**.
+   *
+   * Sets PKARR relays to `http://<host>:15411/` and enables WASM `pubky://`
+   * mapping for that host.
+   *
+   * @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;
+  /**
+   * Perform a raw fetch. Works with `pubky://` or `http(s)://` URLs.
+   *
+   * @param {string} url
+   * @param {RequestInit=} init Standard fetch options; `credentials: "include"` recommended for session I/O.
+   * @returns {Promise<Response>}
+   *
+   * @example
+   * const client = pubky.client();
+   * const res = await client.fetch(`pubky://${user}/pub/app/file.txt`, { method: "PUT", body: "hi", credentials: "include" });
+   */
+  fetch(url: string, init?: any | null): Promise<Promise<any>>;
+}
+export class Keypair {
+  private constructor();
+  free(): void;
+  /**
+   * Generate a random [Keypair]
+   */
+  static random(): Keypair;
+  /**
+   * Generate a [Keypair] from a secret key.
+   */
+  static fromSecretKey(secret_key: Uint8Array): Keypair;
+  /**
+   * Returns the secret key of this keypair.
+   */
+  secretKey(): Uint8Array;
+  /**
+   * Returns the [PublicKey] of this keypair.
+   */
+  publicKey(): PublicKey;
+  /**
+   * Create a recovery file for this keypair (encrypted with the given passphrase).
+   */
+  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;
+}
+/**
+ * Resolve/publish `_pubky` PKDNS records (homeserver pointers).
+ */
+export class Pkdns {
+  free(): 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<string|undefined>} Homeserver public key (z32) or `undefined` if not found.
+   */
+  getHomeserverOf(pubky: PublicKey): Promise<string | undefined>;
+  /**
+   * Resolve the homeserver for **this** user (requires keypair).
+   *
+   * @returns {Promise<string|undefined>} Homeserver public key (z32) or `undefined` if not found.
+   */
+  getHomeserver(): Promise<string | undefined>;
+  /**
+   * 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>}
+   */
+  publishHomeserverForce(host_override?: PublicKey | null): Promise<void>;
+  /**
+   * 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>}
+   */
+  publishHomeserverIfStale(host_override?: PublicKey | null): Promise<void>;
+}
+/**
+ * High-level entrypoint to the Pubky SDK.
+ */
+export class Pubky {
+  free(): void;
+  /**
+   * Create a Pubky façade wired for **mainnet** defaults (public relays).
+   *
+   * @returns {Pubky}
+   * A new façade 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 façade 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 façade.
+   *
+   * @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. Call `authorizationUrl()` to show a QR/deeplink,
+   * then `awaitApproval()` to obtain a `Session`.
+   *
+   * @throws {PubkyJsError}
+   * - `{ 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: string, 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;
+  /**
+   * Public, unauthenticated storage API.
+   *
+   * Use for **read-only** public access via addressed paths:
+   * `"<user-z32>/pub/…"`.
+   *
+   * @returns {PublicStorage}
+   *
+   * @example
+   * const pub = pubky.publicStorage();
+   * const text = await pub.getText(`${userPk.z32()}/pub/example.com/hello.txt`);
+   */
+  publicStorage(): PublicStorage;
+  /**
+   * Read-only PKDNS (Pkarr) resolver.
+   *
+   * @returns {Pkdns}
+   *
+   * @example
+   * const dns = pubky.pkdns();
+   * const homeserver = await dns.getHomeserverOf(userPk);
+   */
+  pkdns(): Pkdns;
+  /**
+   * 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" });
+   */
+  client(): Client;
+}
+export class PublicKey {
+  private constructor();
+  free(): void;
+  /**
+   * Convert the PublicKey to Uint8Array
+   */
+  toUint8Array(): Uint8Array;
+  /**
+   * Returns the z-base32 encoding of this public key
+   */
+  z32(): string;
+  /**
+   * @throws
+   */
+  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://…` absolute URLs.
+   *
+   * @param {string} address Addressed directory (must end with `/`).
+   * @param {string|null=} cursor Optional suffix or full URL to start **after**.
+   * @param {boolean=} reverse Default `false`. When `true`, newest/lexicographically-last first.
+   * @param {number=} limit Optional result limit.
+   * @param {boolean=} shallow Default `false`. When `true`, lists only first-level entries.
+   * @returns {Promise<string[]>}
+   */
+  list(address: string, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+  /**
+   * Fetch bytes from an addressed path.
+   *
+   * @param {string} address
+   * @returns {Promise<Uint8Array>}
+   */
+  getBytes(address: string): Promise<Uint8Array>;
+  /**
+   * Fetch text from an addressed path as UTF-8 text.
+   *
+   * @param {string} address
+   * @returns {Promise<string>}
+   */
+  getText(address: string): Promise<string>;
+  /**
+   * Fetch JSON from an addressed path.
+   *
+   * @param {string} address `"<user-z32>/pub/.../file.json"` or `pubky://<user>/pub/...`.
+   * @returns {Promise<any>}
+   */
+  getJson(address: string): Promise<any>;
+  /**
+   * Check if a path exists.
+   *
+   * @param {string} address
+   * @returns {Promise<boolean>}
+   */
+  exists(address: string): Promise<boolean>;
+  /**
+   * Get metadata for an address
+   *
+   * @param {string} address `"<user-z32>/pub/.../file.json"` or `pubky://<user>/pub/...`.
+   * @returns {Promise<ResourceStats|undefined>} `undefined` if the resource does not exist.
+   * @throws {PubkyJsError} On invalid input or transport/server errors.
+   */
+  stats(address: string): 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;
+  /**
+   * Retrieve immutable info about this session (user & capabilities).
+   *
+   * @returns {SessionInfo}
+   */
+  info(): SessionInfo;
+  /**
+   * Access the session-scoped storage API (read/write).
+   *
+   * @returns {SessionStorage}
+   */
+  storage(): SessionStorage;
+  /**
+   * Invalidate the session on the server (clears server cookie).
+   * It also consumes this JS/Wasm Session. Further calls will fail.
+   *
+   * @returns {Promise<void>}
+   */
+  signout(): Promise<void>;
+}
+/**
+ * Static snapshot of session metadata.
+ */
+export class SessionInfo {
+  private constructor();
+  free(): void;
+  /**
+   * The user’s public key for this session.
+   *
+   * @returns {PublicKey}
+   */
+  publicKey(): PublicKey;
+  /**
+   * Effective capabilities granted to this session.
+   *
+   * @returns {string[]} Normalized capability entries (e.g. `"/pub/app/:rw"`).
+   */
+  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 {string} path Must end with `/`.
+   * @param {string|null=} cursor Optional suffix or full URL to start **after**.
+   * @param {boolean=} reverse Default `false`.
+   * @param {number=} limit Optional result limit.
+   * @param {boolean=} shallow Default `false`.
+   * @returns {Promise<string[]>}
+   */
+  list(path: string, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+  /**
+   * GET bytes from an absolute session path.
+   *
+   * @param {string} path
+   * @returns {Promise<Uint8Array>}
+   */
+  getBytes(path: string): Promise<Uint8Array>;
+  /**
+   * GET text from an absolute session path.
+   *
+   * @param {string} path
+   * @returns {Promise<string>}
+   */
+  getText(path: string): Promise<string>;
+  /**
+   * GET JSON from an absolute session path.
+   *
+   * @param {string} path
+   * @returns {Promise<any>}
+   */
+  getJson(addr: string): Promise<any>;
+  /**
+   * Check existence.
+   *
+   * @param {string} path
+   * @returns {Promise<boolean>}
+   */
+  exists(path: string): Promise<boolean>;
+  /**
+   * Get metadata for an absolute, session-scoped path (e.g. `"/pub/app/file.json"`).
+   *
+   * @param {string} path Absolute path under your user (starts with `/`).
+   * @returns {Promise<ResourceStats|undefined>} `undefined` if the resource does not exist.
+   * @throws {PubkyJsError} On invalid input or transport/server errors.
+   */
+  stats(path: string): Promise<ResourceStats | undefined>;
+  /**
+   * PUT binary at an absolute session path.
+   *
+   * @param {string} path
+   * @param {Uint8Array} bytes
+   * @returns {Promise<void>}
+   */
+  putBytes(path: string, body: Uint8Array): Promise<void>;
+  /**
+   * PUT text at an absolute session path.
+   *
+   * @param {string} path
+   * @param {string} text
+   * @returns {Promise<void>}
+   */
+  putText(path: string, body: string): Promise<void>;
+  /**
+   * PUT JSON at an absolute session path.
+   *
+   * @param {string} path Absolute path (e.g. `"/pub/app/data.json"`).
+   * @param {any} value JSON-serializable value.
+   * @returns {Promise<void>}
+   */
+  putJson(path: string, body: any): Promise<void>;
+  /**
+   * Delete a path (file or empty directory).
+   *
+   * @param {string} path
+   * @returns {Promise<void>}
+   */
+  delete(path: string): 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;
+  /**
+   * Get the public key of this signer.
+   *
+   * @returns {PublicKey}
+   */
+  publicKey(): PublicKey;
+  /**
+   * 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 {PubkyJsError}
+   * - `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 {PubkyJsError}
+   */
+  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 a PKDNS actor bound to this signer's client & keypair (publishing enabled).
+   *
+   * @returns {Pkdns}
+   */
+  pkdns(): Pkdns;
+}