Struct Pubky 

pub struct Pubky { /* private fields */ }

High-level facade. Owns a PubkyHttpClient and constructs the main actors. 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.

Implementations

impl Pubky

pub fn new() -> Result<Self>

Construct with defaults (mainnet relays, standard timeouts).

Errors

• Returns crate::errors::Error when the underlying PubkyHttpClient fails to initialize (e.g., TLS configuration or relay/bootstrap setup issues).

pub fn testnet() -> Result<Self>

Construct preconfigured for a local Pubky testnet.

Errors

• Returns crate::errors::Error when the testnet-configured PubkyHttpClient cannot be created (for example, invalid local relay/testnet configuration).

pub const fn with_client(client: PubkyHttpClient) -> Self

Construct from an already-configured transport.

pub fn start_auth_flow( &self, caps: &Capabilities, auth_kind: AuthFlowKind, ) -> Result<PubkyAuthFlow>

Start an end-to-end auth flow (QR/deeplink). Depending on the auth kind, the flow will be different.

• AuthFlowKind::SignIn - Sign in to an existing account.
• AuthFlowKind::SignUp - Sign up for a new account.

Use with flow.authorization_url() and then await_approval() (blocking) or try_poll_once() (non-blocking UI loops).

Errors

• crate::errors::Error::Parse if internal URL construction for the flow fails (e.g., malformed relay URL when configured via the builder).

pub fn resume_auth_flow(&self, authorization_url: &str) -> Result<PubkyAuthFlow>

Resume a previously started auth flow from its authorization_url.

Parses the secret, capabilities, relay, and flow kind from the URL and rebuilds the flow against the same relay channel. If the signer already approved, the first try_poll_once() returns a session.

The relay inbox persists messages for ~5 minutes; resume is only viable within that window. After the TTL expires the channel is gone and you must start a fresh flow with start_auth_flow.

The authorization_url contains the client_secret; follow start_auth_flow storage guidance and delete it once resume completes or is abandoned.

Errors

• Returns crate::errors::Error::Authentication if the URL cannot be parsed or is not a signin/signup deep link.

pub fn signer(&self, keypair: Keypair) -> PubkySigner

Create a PubkySigner for a given keypair.

pub fn public_storage(&self) -> PublicStorage

Create a public, unauthenticated storage handle using this facade’s client.

pub fn pkdns(&self) -> Pkdns

Read-only Pkdns actor (resolve _pubky records) using this facade’s client.

pub async fn get_homeserver_of( &self, user_public_key: &PublicKey, ) -> Option<PublicKey>

Resolve current homeserver host for a user public key via Pkarr.

Returns the _pubky SVCB/HTTPS target (domain or pubkey-as-host), or None if the record is missing/unresolvable. Uses an internal read-only Pkdns actor.

pub fn event_stream_for_user( &self, user: &PublicKey, cursor: Option<EventCursor>, ) -> 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.

Example

use pubky::{Pubky, PublicKey, EventCursor};
use futures_util::StreamExt;

let pubky = Pubky::new()?;
let user = PublicKey::try_from("o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo").unwrap();

let mut stream = pubky.event_stream_for_user(&user, None)
    .live()
    .subscribe()
    .await?;

while let Some(result) = stream.next().await {
    let event = result?;
    println!("Event: {:?} at {}", event.event_type, event.resource);
}

pub fn event_stream_for(&self, homeserver: &PublicKey) -> EventStreamBuilder

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 Self::get_homeserver_of.

Example

use pubky::{Pubky, PublicKey};
use futures_util::StreamExt;

let pubky = Pubky::new()?;
let user1 = PublicKey::try_from("o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo").unwrap();
let user2 = PublicKey::try_from("pxnu33x7jtpx9ar1ytsi4yxbp6a5o36gwhffs8zoxmbuptici1jy").unwrap();

// When subscribing to multiple users on the same homeserver,
// specify the homeserver directly to avoid redundant Pkarr lookups
let homeserver = pubky.get_homeserver_of(&user1).await.unwrap();

let mut stream = pubky.event_stream_for(&homeserver)
    .add_users([(&user1, None), (&user2, None)])?
    .subscribe()
    .await?;

while let Some(result) = stream.next().await {
    let event = result?;
    println!("Event: {:?} at {}", event.event_type, event.resource);
}

pub async fn session_from_file<P: AsRef<Path>>( &self, path: P, ) -> Result<PubkySession>

Restore a session from a .sess secret file.

Errors

• Returns crate::errors::Error::Request if the secret file cannot be read.
• Returns crate::errors::RequestError::Validation when the file contents are malformed.
• Propagates transport errors from PubkySession::from_secret_file if the client cannot be prepared.

pub fn signer_from_recovery_file<P: AsRef<Path>>( &self, path: P, passphrase: &str, ) -> Result<PubkySigner>

Recover a keypair from an encrypted .pkarr secret file and return a PubkySigner.

Errors

• Returns crate::errors::Error::Request when reading the recovery file fails.
• Returns crate::errors::Error::Request when decryption fails (invalid passphrase or corrupted file).

pub const fn client(&self) -> &PubkyHttpClient

Access the underlying transport (advanced use).

Trait Implementations

impl Clone for Pubky

fn clone(&self) -> Pubky

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Pubky

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.