atproto_extras/lib.rs
1//! Extra utilities for AT Protocol applications.
2//!
3//! This crate provides additional utilities that complement the core AT Protocol
4//! identity and record crates. Currently, it focuses on rich text facet parsing.
5//!
6//! ## Features
7//!
8//! - **Facet Parsing**: Extract mentions, URLs, and hashtags from plain text
9//! with correct UTF-8 byte offset calculation
10//! - **Identity Integration**: Resolve mention handles to DIDs during parsing
11//!
12//! ## Example
13//!
14//! ```ignore
15//! use atproto_extras::{parse_facets_from_text, FacetLimits};
16//!
17//! // Parse facets from text (requires an IdentityResolver)
18//! let text = "Hello @alice.bsky.social! Check out https://example.com #rust";
19//! let limits = FacetLimits::default();
20//! let facets = parse_facets_from_text(text, &resolver, &limits).await;
21//! ```
22//!
23//! ## Byte Offset Calculation
24//!
25//! This implementation correctly uses UTF-8 byte offsets as required by AT Protocol.
26//! The facets use "inclusive start and exclusive end" byte ranges. All parsing is done
27//! using `regex::bytes::Regex` which operates on byte slices and returns byte positions,
28//! ensuring correct handling of multi-byte UTF-8 characters (emojis, CJK, accented chars).
29
30#![forbid(unsafe_code)]
31#![warn(missing_docs)]
32
33/// Rich text facet parsing for AT Protocol.
34///
35/// This module provides functionality for extracting semantic annotations (facets)
36/// from plain text. Facets include:
37///
38/// - **Mentions**: User handles prefixed with `@` (e.g., `@alice.bsky.social`)
39/// - **Links**: HTTP/HTTPS URLs
40/// - **Tags**: Hashtags prefixed with `#` or `＃` (e.g., `#rust`)
41///
42/// ## Byte Offsets
43///
44/// All facet indices use UTF-8 byte offsets, not character indices. This is
45/// critical for correct handling of multi-byte characters like emojis or
46/// non-ASCII text.
47pub mod facets;
48
49/// Re-export commonly used types for convenience.
50pub use facets::{FacetLimits, parse_facets_from_text, parse_mentions, parse_tags, parse_urls};