openagents_sdk

Account

pub struct Account {
    pub id: String,
    pub label: String,
    pub email: Option<String>,
    pub avatar_url: Option<String>,
}

A signed-in account: its ID, display label, and optional email and avatar.

AccountView

pub struct AccountView {
    pub account: Account,
    pub workspaces: Vec<Workspace>,
}

The account and its current workspaces, as [Client::account] returns them.

Client

pub struct Client {}

A bounded client for one deployment that refuses redirects. Auth and history send once; the Computers facade applies its own operation-specific retry policy.

pub fn new(deployment: Deployment) -> Result<Self, Error>

pub fn with_timeout(deployment: Deployment, timeout: Duration) -> Result<Self, Error>

pub fn with_timeouts(
    deployment: Deployment,
    connect_timeout: Duration,
    timeout: Duration,
) -> Result<Self, Error>

pub fn with_test_run(
    deployment: Deployment,
    timeout: Duration,
    test_run: bool,
) -> Result<Self, Error>

pub fn deployment(&self) -> &Deployment

CredentialRecord

pub struct CredentialRecord {}

Explicit persistence payload. Serialize only into the application's credential store.

pub fn deployment(&self) -> &Deployment

pub fn account(&self) -> &Account

pub fn expires_at(&self) -> Option<u64>

pub fn expired(&self, now: u64) -> bool

CredentialStore

pub trait CredentialStore {
    fn load(
        &self,
        deployment: &Deployment,
    ) -> Result<Option<CredentialRecord>, StorageError>;
    fn save(&self, record: &CredentialRecord) -> Result<(), StorageError>;
    fn clear(&self, deployment: &Deployment) -> Result<(), StorageError>;
}

Caller-owned persistence. Implement with Keychain, another OS store, or memory.

fn load(
    &self,
    deployment: &Deployment,
) -> Result<Option<CredentialRecord>, StorageError>

fn save(&self, record: &CredentialRecord) -> Result<(), StorageError>

fn clear(&self, deployment: &Deployment) -> Result<(), StorageError>

Deployment

pub struct Deployment {}

The two explicit addresses belonging to one deployment.

pub fn new(api_base: &str, website: &str) -> Result<Self, Error>

pub fn production() -> Self

pub fn api_base(&self) -> &Url

pub fn website(&self) -> &Url

Error

pub enum Error {
    InvalidDeployment,
    InvalidTimeout,
    InvalidCredential,
    WrongDeployment,
    WrongAccount,
    ExpiredSession,
    Unauthorized,
    Forbidden,
    Denied,
    KeyDenied,
    ExpiredLogin,
    FinishedLogin,
    Cancelled,
    UncertainLogin(Box<Error>),
    Network { timeout: bool },
    InvalidResponse,
    NotFound,
    Changed,
    InvalidCursor,
    InvalidReference,
    TooLarge,
    Redirect,
    PaymentRequired(crate::PaymentRequired),
    RateLimited { retry_after: Option<Duration> },
    Unavailable { retry_after: Option<Duration> },
    Refused { status: u16, code: Option<&'static str> },
}

Error diagnostics omit response bodies, credential values, request URLs, and the HTTP 402 headers available through the explicit accessor.

pub fn payment_required(&self) -> Option<&crate::PaymentRequired>

EventTemplate

pub struct EventTemplate {
    pub created_at: u64,
    pub kind: u16,
    pub tags: Vec<Vec<String>>,
    pub content: String,
}

An unsigned NIP-01 event for the signer to complete with id, pubkey, and sig.

KeySignIn

pub struct KeySignIn {
    pub session: Session,
    pub created: bool,
    pub pubkey: String,
}

A completed key sign-in.

LinkedKey

pub struct LinkedKey {
    pub pubkey: String,
    pub npub: String,
}

One of the account's keys.

Login

pub struct Login {}

A single login attempt. Drop or cancel it to stop waiting; no credential is saved.

pub fn user_code(&self) -> &str

pub fn verification_url(&self) -> &Url

pub fn expires_in(&self) -> Duration

pub fn next_poll_in(&self) -> Duration

pub fn cancel(&mut self)

NostrSigner

pub trait NostrSigner: Send + Sync {
    fn sign_event(&self, template: &EventTemplate) -> Result<String, SignerError>;
}

Signs events with the caller's key. The SDK only asks for signatures.

fn sign_event(&self, template: &EventTemplate) -> Result<String, SignerError>

PaymentRequired

pub struct PaymentRequired {}

An untrusted PAYMENT-REQUIRED header from an HTTP 402 response.

The SDK preserves the header without parsing, paying, or following any URL it contains. An application must validate the offer, invoice, and actual request through its separately authorized payment integration before spending. Debug output omits the header, which can contain private request details.

pub fn header(&self) -> Result<&str, PaymentRequiredHeaderError>

PaymentRequiredHeaderError

pub enum PaymentRequiredHeaderError {
    Missing,
    Repeated,
    TooLarge,
    InvalidText,
}

Why an HTTP 402 did not supply one usable text header.

Poll

pub enum Poll {
    Pending { retry_after: Duration },
    SlowDown { retry_after: Duration },
    SignedIn(Session),
}

The result of one login poll: keep waiting, slow down, or signed in.

ScannedLogin

pub struct ScannedLogin {
    pub origin: String,
}

A website login the phone scanned. The challenge is a one-time capability: never log it.

pub fn parse(text: &str) -> Option<Self>

ScannedLoginAbout

pub struct ScannedLoginAbout {
    pub browser: String,
    pub expires_at: u64,
}

Which browser a scanned login is for.

ScannedLoginApproved

pub struct ScannedLoginApproved {
    pub browser: String,
    pub created: bool,
}

An approved website login.

Session

pub struct Session {}

An authenticated account, bound to its exact API/website pair.

pub fn account(&self) -> &Account

pub fn expires_at(&self) -> Option<u64>

pub fn deployment(&self) -> &Deployment

pub fn record(&self) -> CredentialRecord

pub fn bearer_token(&self) -> &str

SignerError

pub struct SignerError;

Why a signer didn't sign.

StorageError

pub enum StorageError {
    Denied,
    Unavailable,
}

Why a credential store couldn't load, save, or clear a login.

Workspace

pub struct Workspace {
    pub id: String,
    pub name: String,
    pub role: String,
    pub kind: String,
    pub tenant: String,
}

A workspace the account belongs to, with the account's role in it.

solve_pow

pub fn solve_pow(challenge: &str, bits: u8) -> String

Solve the sign-up proof of work over challenge: the first counter, in decimal, whose SHA-256(challenge ":" counter) starts with bits zero bits. About a million hashes at 20 bits: run it off the UI thread.

DELETE_ACCOUNT_CONFIRM

pub const DELETE_ACCOUNT_CONFIRM: &str = "delete my account";

The words DELETE /v1/account asks for, sent after the person confirms in the app.

HTTP_AUTH_KIND

pub const HTTP_AUTH_KIND: u16 = 27_235;

The NIP-98 HTTP authorization kind.

KEY_BODY_MAX

pub const KEY_BODY_MAX: usize = 16 * 1024;

The largest sign-in body the server takes (oa_auth::nostr::BODY_MAX).

MAX_PAYMENT_REQUIRED_HEADER_BYTES

pub const MAX_PAYMENT_REQUIRED_HEADER_BYTES: usize = 64 * 1024;

The same encoded-header limit used by the existing x402 HTTP codec.

POW_BITS

pub const POW_BITS: u8 = 20;

The proof-of-work difficulty a new key's first sign-in needs by default (#11994): leading zero bits of SHA-256(challenge ":" solution).