proto-blue-api 0.3.1

AT Protocol high-level API: agent, rich text, moderation, generated types
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# proto-blue-api

High-level AT Protocol client -- Agent, RichText, moderation, and generated types from 322 Lexicon schemas.

## Installation

```toml
[dependencies]
proto-blue-api = "0.3"
```

## Exports

- `Agent`, `Session`, `AgentError` -- authenticated API client
- `RichText`, `RichTextSegment`, `Facet`, `FacetFeature`, `detect_facets` -- rich text processing
- `ModerationDecision`, `ModerationOpts`, `check_muted_words`, `known_labels` -- content moderation
- `generated::` -- types generated from AT Protocol Lexicon schemas

Identifier types (`Did`, `Handle`, `AtUri`, `AtIdentifier`, ...) live in `proto_blue_syntax`; CIDs live in `proto_blue_lex_data`. The Agent surface and generated XRPC parameters take these by reference instead of `&str`.

## Usage

### Agent

```rust
use proto_blue_api::Agent;
use proto_blue_syntax::AtIdentifier;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let agent = Agent::new("https://bsky.social")?;
    let ident = AtIdentifier::new("alice.bsky.social")?;
    agent.login(&ident, "app-password").await?;
    agent.post("Hello from Rust!", None, None).await?;
    Ok(())
}
```

### RichText

```rust
use proto_blue_api::rich_text::{RichText, FacetFeature};

let mut rt = RichText::new("Hello @alice.bsky.social! #atproto".to_string(), None);
rt.detect_facets();
for seg in &rt.segments() {
    if let Some(facet) = &seg.facet {
        match &facet.features[0] {
            FacetFeature::Mention { did } => println!("@{did}"),
            FacetFeature::Link { uri } => println!("{uri}"),
            FacetFeature::Tag { tag } => println!("#{tag}"),
        }
    }
}
```

## Migrating from 0.2.x

v0.3.0 replaces `String`/`&str` identifier arguments and fields with validated newtypes from `proto_blue_syntax`. Wire format is unchanged; callers construct typed values explicitly.

```rust
use proto_blue_syntax::{Did, Handle, AtUri, AtIdentifier};
use proto_blue_lex_data::Cid;
```

Common swaps:

- `agent.login("alice.bsky.social", pw)` -> `agent.login(&AtIdentifier::new("alice.bsky.social")?, pw)`
- `agent.resolve_handle("alice.bsky.social")` -> `agent.resolve_handle(&Handle::new("alice.bsky.social")?)` (now returns `Did`)
- `agent.follow(&did_str, ...)` -> `agent.follow(&Did::new(did_str)?, ...)`
- `agent.like(&uri_str, &cid_str, ...)` -> `agent.like(&AtUri::new(uri_str)?, &Cid::new(cid_str)?, ...)`
- `agent.delete_post(&uri_str)` (and `delete_like` / `delete_repost` / `delete_follow`) -> pass `&AtUri`
- `agent.get_post_thread(&uri_str, ...)` -> `&AtUri`; `agent.get_profile(&actor_str, ...)` -> `&AtIdentifier`
- `agent.create_account(&handle_str, pw, email, ...)` -> `&Handle`
- `Session.did: String` -> `Did`; `Session.handle: String` -> `Handle`; `LabelerOpts.did: String` -> `Did`. `access_jwt`, `refresh_jwt`, and `email` remain `String`.
- `Agent::did() -> Option<Did>` (was `Option<String>`).

`resume_session` and `resolve_handle` now validate server-returned DIDs through `Did::new`; a malformed DID surfaces as `AgentError::Other(...)` instead of being stored verbatim.

Generated XRPC method parameters whose lexicons declare a `format`-typed string (did, handle, at-uri, cid, nsid, ...) now expose the corresponding newtype on the request struct.

## License

Licensed under MIT OR Apache-2.0.

Part of the [proto-blue](https://github.com/dollspace-gay/proto-blue) AT Protocol SDK for Rust.