Skip to main content

nb_api/
types.rs

1//! Public wire types for body-aware reads, edits, and commit outcomes.
2
3use serde::{Deserialize, Serialize};
4
5use crate::error::NbError;
6use crate::fingerprint::Fingerprint;
7use crate::parser::{DocumentKind, TodoState};
8
9/// Arbitrary file bytes on the wire as standard base64.
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
12pub struct ByteString {
13    pub base64: String,
14}
15
16impl ByteString {
17    pub fn from_bytes(bytes: impl AsRef<[u8]>) -> Self {
18        use base64::Engine;
19        Self {
20            base64: base64::engine::general_purpose::STANDARD.encode(bytes.as_ref()),
21        }
22    }
23
24    pub fn as_bytes(&self) -> Result<Vec<u8>, NbError> {
25        use base64::Engine;
26        base64::engine::general_purpose::STANDARD
27            .decode(self.base64.as_bytes())
28            .map_err(|e| NbError::ValidationError {
29                reason: format!("invalid ByteString base64: {e}"),
30                location: None,
31            })
32    }
33}
34
35/// Address an existing note by selector or notebook-relative path.
36#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
37#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
38#[serde(tag = "type", rename_all = "lowercase")]
39pub enum NoteTarget {
40    Selector { value: String },
41    Path { value: String },
42}
43
44impl NoteTarget {
45    pub fn selector(value: impl Into<String>) -> Self {
46        Self::Selector {
47            value: value.into(),
48        }
49    }
50
51    pub fn path(value: impl Into<String>) -> Self {
52        Self::Path {
53            value: value.into(),
54        }
55    }
56
57    pub fn value(&self) -> &str {
58        match self {
59            Self::Selector { value } | Self::Path { value } => value,
60        }
61    }
62}
63
64/// One body fragment exposed by structured show.
65#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
66#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
67pub struct BodyFragment {
68    pub index: u32,
69    pub bytes: ByteString,
70}
71
72/// Structured `show_note` result.
73#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
74#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
75pub struct ShowNote {
76    pub selector: String,
77    pub path: String,
78    pub kind: DocumentKind,
79    pub todo_state: Option<TodoState>,
80    pub title: Option<ByteString>,
81    pub title_text: Option<String>,
82    pub tags: Vec<String>,
83    pub body_fragments: Vec<BodyFragment>,
84    pub body_contiguous: bool,
85    pub body: ByteString,
86    pub fingerprint: Fingerprint,
87    pub source: ByteString,
88}
89
90/// Versioned body-line authenticity token: `b3l1:<32 lowercase hex>`.
91#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
92#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
93#[serde(transparent)]
94pub struct LineAnchor(String);
95
96impl LineAnchor {
97    pub const PREFIX: &'static str = "b3l1:";
98
99    pub fn as_str(&self) -> &str {
100        &self.0
101    }
102
103    pub fn from_line_bytes(line_with_terminator_or_eof_marker: &[u8]) -> Self {
104        let hash = blake3::hash(line_with_terminator_or_eof_marker);
105        let hex = hash.to_hex();
106        Self(format!("{}{}", Self::PREFIX, &hex[..32]))
107    }
108
109    pub fn parse(s: &str) -> Result<Self, NbError> {
110        if !s.starts_with(Self::PREFIX) {
111            return Err(NbError::ValidationError {
112                reason: format!("unknown line anchor prefix in {s:?}"),
113                location: None,
114            });
115        }
116        let hex = &s[Self::PREFIX.len()..];
117        if hex.len() != 32
118            || !hex
119                .chars()
120                .all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
121        {
122            return Err(NbError::ValidationError {
123                reason: format!("invalid line anchor hex in {s:?}"),
124                location: None,
125            });
126        }
127        Ok(Self(s.to_string()))
128    }
129}
130
131impl std::fmt::Display for LineAnchor {
132    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
133        f.write_str(&self.0)
134    }
135}
136
137/// Line terminator as stored in the body.
138#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
139#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
140#[serde(rename_all = "lowercase")]
141pub enum LineTerminator {
142    Lf,
143    Crlf,
144    Cr,
145    None,
146}
147
148/// One enumerated body line.
149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
150#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
151pub struct NoteLine {
152    pub number: u32,
153    pub anchor: LineAnchor,
154    pub text: ByteString,
155    pub terminator: LineTerminator,
156}
157
158/// Windowed body-line listing.
159#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
160#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
161pub struct ShowNoteLines {
162    pub selector: String,
163    pub path: String,
164    pub kind: DocumentKind,
165    pub total_lines: u32,
166    pub offset: u32,
167    pub limit: u32,
168    pub next_offset: Option<u32>,
169    pub lines: Vec<NoteLine>,
170    pub title: Option<ByteString>,
171    pub tags: Vec<String>,
172    pub body_fingerprint: Fingerprint,
173}
174
175/// Number + anchor reference to a body line.
176#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
177#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
178pub struct LineRef {
179    pub number: u32,
180    pub anchor: LineAnchor,
181}
182
183/// Insert position relative to a line or body boundary.
184#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
185#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
186#[serde(tag = "type", rename_all = "lowercase")]
187pub enum LinePosition {
188    Before { line: LineRef },
189    After { line: LineRef },
190    Boundary { at: BoundaryAt },
191}
192
193/// Virtual body boundaries (`^` / `$`).
194#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
195#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
196#[serde(rename_all = "lowercase")]
197pub enum BoundaryAt {
198    Caret,
199    Dollar,
200}
201
202/// One line-oriented edit in an `edit_note_lines` batch.
203#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
204#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
205#[serde(tag = "type", rename_all = "lowercase")]
206pub enum LineEdit {
207    Insert {
208        at: LinePosition,
209        content: ByteString,
210    },
211    Delete {
212        start: LineRef,
213        end: LineRef,
214    },
215    Replace {
216        start: LineRef,
217        end: LineRef,
218        content: ByteString,
219    },
220}
221
222/// Substring occurrence selector.
223#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
224#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
225#[serde(tag = "type", rename_all = "lowercase")]
226pub enum Occurrence {
227    First,
228    All,
229    Nth { n: u32 },
230}
231
232/// One search hit within a body line.
233#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
234#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
235pub struct NoteLineHit {
236    pub number: u32,
237    pub anchor: LineAnchor,
238    pub start_byte: u32,
239    pub end_byte: u32,
240    #[serde(skip_serializing_if = "Option::is_none")]
241    pub text: Option<ByteString>,
242}
243
244/// Result of `search_note_lines`.
245#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
246#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
247pub struct SearchNoteLines {
248    pub selector: String,
249    pub path: String,
250    pub kind: DocumentKind,
251    pub hits: Vec<NoteLineHit>,
252    pub body_fingerprint: Fingerprint,
253}
254
255/// Outcome of one plan op after a successful commit.
256#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
257#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
258pub struct OpOutcome {
259    pub index: u32,
260    pub path: Option<String>,
261    pub selector: Option<String>,
262    pub noop: bool,
263    #[serde(skip_serializing_if = "Option::is_none")]
264    pub fingerprint: Option<Fingerprint>,
265}
266
267/// Structured result of [`crate::Transaction::commit`].
268#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
269#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
270pub struct CommitOutcome {
271    pub commit_created: bool,
272    pub revision_id: Option<String>,
273    pub pre_revision: String,
274    pub ops: Vec<OpOutcome>,
275}