Skip to main content

semora_proto/
lib.rs

1//! Shared API types and websocket messages for Semora.
2//!
3//! Every HTTP response body and websocket frame exchanged between
4//! `semora-server`, `semora` (the CLI) and the browser is defined here.
5
6use std::fmt;
7use std::str::FromStr;
8
9use serde::{Deserialize, Serialize};
10use serde_json::Value;
11use time::OffsetDateTime;
12
13/// The guide for people and agents, served at `/docs` and printed by `semora skill`.
14pub const GUIDE: &str = include_str!("../guide.md");
15/// A deleted document is kept this many days, then purged. The server purges by it, and the
16/// CLI, the guide and the pages state it.
17pub const DELETED_RETENTION_DAYS: i64 = 7;
18
19/// Websocket subprotocol spoken on `/ws/d/{id}`.
20pub const SUBPROTOCOL: &str = "semora.v1";
21/// Prefix of every API route.
22pub const API_PREFIX: &str = "/api/v1";
23/// Largest websocket frame either side may send.
24pub const MAX_WS_MESSAGE: usize = 64 * 1024;
25/// Largest `data` payload of a `page_event`.
26pub const MAX_PAGE_EVENT_DATA: usize = 64 * 1024;
27/// Largest screenshot attachment.
28pub const MAX_ATTACHMENT: usize = 5 * 1024 * 1024;
29
30#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
31#[serde(rename_all = "lowercase")]
32pub enum DocKind {
33    Md,
34    Html,
35    Bundle,
36}
37
38impl DocKind {
39    pub fn as_str(self) -> &'static str {
40        match self {
41            DocKind::Md => "md",
42            DocKind::Html => "html",
43            DocKind::Bundle => "bundle",
44        }
45    }
46}
47
48impl fmt::Display for DocKind {
49    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
50        f.write_str(self.as_str())
51    }
52}
53
54impl FromStr for DocKind {
55    type Err = String;
56    fn from_str(s: &str) -> Result<Self, Self::Err> {
57        match s {
58            "md" => Ok(DocKind::Md),
59            "html" => Ok(DocKind::Html),
60            "bundle" => Ok(DocKind::Bundle),
61            other => Err(format!("unknown document kind `{other}`")),
62        }
63    }
64}
65
66/// What a person may do in a project. The order is the order of power:
67/// `Viewer < Reviewer < Editor < Owner`.
68#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
69#[serde(rename_all = "lowercase")]
70pub enum Level {
71    Viewer,
72    Reviewer,
73    Editor,
74    Owner,
75}
76
77impl Level {
78    pub fn as_str(self) -> &'static str {
79        match self {
80            Level::Viewer => "viewer",
81            Level::Reviewer => "reviewer",
82            Level::Editor => "editor",
83            Level::Owner => "owner",
84        }
85    }
86
87    /// The word the UI shows: `Viewer`, `Reviewer`, `Editor`, `Owner`.
88    pub fn label(self) -> &'static str {
89        match self {
90            Level::Viewer => "Viewer",
91            Level::Reviewer => "Reviewer",
92            Level::Editor => "Editor",
93            Level::Owner => "Owner",
94        }
95    }
96}
97
98impl fmt::Display for Level {
99    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100        f.write_str(self.as_str())
101    }
102}
103
104impl FromStr for Level {
105    type Err = String;
106    fn from_str(s: &str) -> Result<Self, Self::Err> {
107        match s {
108            "viewer" => Ok(Level::Viewer),
109            "reviewer" => Ok(Level::Reviewer),
110            "editor" => Ok(Level::Editor),
111            "owner" => Ok(Level::Owner),
112            other => Err(format!("unknown level `{other}`")),
113        }
114    }
115}
116
117/// A serde default for a sender that predates levels, which could only be the owner.
118pub fn owner_level() -> Level {
119    Level::Owner
120}
121
122/// Who a piece of feedback, a message or a revision is from.
123#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
124pub struct Person {
125    pub id: i64,
126    pub name: String,
127}
128
129/// API key scopes.
130#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
131pub enum Scope {
132    #[serde(rename = "docs:write")]
133    DocsWrite,
134    #[serde(rename = "docs:read")]
135    DocsRead,
136    #[serde(rename = "events")]
137    Events,
138}
139
140impl Scope {
141    pub fn all() -> Vec<Scope> {
142        vec![Scope::DocsWrite, Scope::DocsRead, Scope::Events]
143    }
144
145    pub fn as_str(self) -> &'static str {
146        match self {
147            Scope::DocsWrite => "docs:write",
148            Scope::DocsRead => "docs:read",
149            Scope::Events => "events",
150        }
151    }
152
153    /// Parses a comma-separated scope list such as `docs:write,events`.
154    pub fn parse_list(s: &str) -> Result<Vec<Scope>, String> {
155        s.split(',')
156            .map(str::trim)
157            .filter(|p| !p.is_empty())
158            .map(Scope::from_str)
159            .collect()
160    }
161
162    pub fn join(scopes: &[Scope]) -> String {
163        scopes
164            .iter()
165            .map(|s| s.as_str())
166            .collect::<Vec<_>>()
167            .join(",")
168    }
169}
170
171impl FromStr for Scope {
172    type Err = String;
173    fn from_str(s: &str) -> Result<Self, Self::Err> {
174        match s {
175            "docs:write" => Ok(Scope::DocsWrite),
176            "docs:read" => Ok(Scope::DocsRead),
177            "events" => Ok(Scope::Events),
178            other => Err(format!("unknown scope `{other}`")),
179        }
180    }
181}
182
183/// A relative link inside a pushed document that points at a file the bundle lacks.
184#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
185pub struct BrokenLink {
186    /// The file containing the link.
187    pub from: String,
188    /// The link target as written.
189    pub href: String,
190}
191
192/// Returned by every create or replace.
193#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
194pub struct PushResponse {
195    pub id: String,
196    pub rev: i64,
197    pub kind: DocKind,
198    pub url: String,
199    pub ws_url: String,
200    pub files: usize,
201    pub title: String,
202    /// True when the files, entry page and kind equal the current revision's: the push made no
203    /// revision, `rev` is the current one, and open pages were not reloaded. The title, tags
204    /// and meta of the push still applied. An older server leaves it out, which reads as false.
205    #[serde(default)]
206    pub unchanged: bool,
207    #[serde(default, skip_serializing_if = "Vec::is_empty")]
208    pub broken_links: Vec<BrokenLink>,
209    #[serde(default, skip_serializing_if = "Vec::is_empty")]
210    pub warnings: Vec<String>,
211    /// The project id, when the document is in a project.
212    #[serde(default, skip_serializing_if = "Option::is_none")]
213    pub project: Option<String>,
214    /// The document's path inside the project.
215    #[serde(default, skip_serializing_if = "Option::is_none")]
216    pub path: Option<String>,
217    /// The path link: `{server}/p/{project}/{path}`.
218    #[serde(default, skip_serializing_if = "Option::is_none")]
219    pub path_url: Option<String>,
220}
221
222#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
223pub struct DocSummary {
224    pub id: String,
225    pub title: String,
226    pub kind: DocKind,
227    pub tags: Vec<String>,
228    pub rev: i64,
229    /// Number of stored revisions (older ones are pruned).
230    pub revision_count: i64,
231    pub url: String,
232    #[serde(with = "time::serde::rfc3339")]
233    pub created_at: OffsetDateTime,
234    #[serde(with = "time::serde::rfc3339")]
235    pub updated_at: OffsetDateTime,
236    /// The project id, when the document is in a project.
237    #[serde(default, skip_serializing_if = "Option::is_none")]
238    pub project: Option<String>,
239    /// The document's path inside the project.
240    #[serde(default, skip_serializing_if = "Option::is_none")]
241    pub path: Option<String>,
242    /// The path link: `{server}/p/{project}/{path}`.
243    #[serde(default, skip_serializing_if = "Option::is_none")]
244    pub path_url: Option<String>,
245    /// The caller's level on the document. Set by list and detail.
246    #[serde(default, skip_serializing_if = "Option::is_none")]
247    pub level: Option<Level>,
248}
249
250#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
251pub struct ListResponse {
252    pub docs: Vec<DocSummary>,
253    #[serde(default, skip_serializing_if = "Option::is_none")]
254    pub next_cursor: Option<String>,
255}
256
257/// A project as the API returns it.
258#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
259pub struct ProjectInfo {
260    /// The project id people type and see in links.
261    pub slug: String,
262    /// The display name.
263    pub name: String,
264    /// The project page.
265    pub url: String,
266    /// Live documents in the project.
267    pub documents: i64,
268    #[serde(with = "time::serde::rfc3339")]
269    pub created_at: OffsetDateTime,
270    /// The newest live document's time, else the project's own.
271    #[serde(with = "time::serde::rfc3339")]
272    pub updated_at: OffsetDateTime,
273    /// The caller's level in the project. A server that predates collaboration only listed the
274    /// caller's own projects.
275    #[serde(default = "owner_level")]
276    pub level: Level,
277    /// The owner's display name.
278    #[serde(default, skip_serializing_if = "Option::is_none")]
279    pub owner: Option<String>,
280}
281
282/// `POST /api/v1/projects`: create a project, or link your existing one with that id.
283#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
284pub struct CreateProject {
285    pub slug: String,
286    /// Defaults to the slug. Ignored when linking an existing project.
287    #[serde(default, skip_serializing_if = "Option::is_none")]
288    pub name: Option<String>,
289    /// Link a project you collaborate on but don't own. Without it that is a 409
290    /// ([`JoinNeeded`]): anyone can be added to a project without being asked, so linking
291    /// one, and publishing into it, is the person's own choice.
292    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
293    pub join: bool,
294}
295
296/// The 409 of `POST /api/v1/projects` for a project you collaborate on, when you didn't ask
297/// to join it. `error` is `join_needed`.
298#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
299pub struct JoinNeeded {
300    pub error: String,
301    pub message: String,
302    /// The owner's display name.
303    pub owner: String,
304    /// Your level in the project.
305    pub level: Level,
306}
307
308/// `PATCH /api/v1/projects/{slug}`.
309#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
310pub struct PatchProject {
311    pub name: String,
312    /// A new project id. Left out, the id stays. The old id becomes an alias for as long as
313    /// the server's alias setting says, so old links and checkouts still find the project.
314    #[serde(default, skip_serializing_if = "Option::is_none")]
315    pub slug: Option<String>,
316}
317
318#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
319pub struct ProjectList {
320    pub projects: Vec<ProjectInfo>,
321}
322
323/// One mapping rule: documents whose path matches `pattern` show inside `folder`
324/// in the project's tree. `folder` is `/` for the project root.
325#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
326pub struct Mapping {
327    pub pattern: String,
328    pub folder: String,
329}
330
331/// A project's mapping rules, in order. The first match wins.
332#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
333pub struct MappingList {
334    pub mappings: Vec<Mapping>,
335}
336
337#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
338pub struct FileInfo {
339    pub path: String,
340    pub size: u64,
341    pub mime: String,
342    pub hash: String,
343}
344
345#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
346pub struct RevisionInfo {
347    pub rev: i64,
348    #[serde(with = "time::serde::rfc3339")]
349    pub created_at: OffsetDateTime,
350    #[serde(default, skip_serializing_if = "Option::is_none")]
351    pub message: Option<String>,
352    pub files: usize,
353    /// Name of the API key that pushed the revision, if any.
354    #[serde(default, skip_serializing_if = "Option::is_none")]
355    pub created_by: Option<String>,
356    /// The person who pushed the revision.
357    #[serde(default, skip_serializing_if = "Option::is_none")]
358    pub pushed_by: Option<Person>,
359    /// Where the revision was pushed from: machine name and git branch.
360    #[serde(default, skip_serializing_if = "Option::is_none")]
361    pub origin: Option<String>,
362}
363
364#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
365pub struct DocDetail {
366    #[serde(flatten)]
367    pub summary: DocSummary,
368    pub entry_path: String,
369    pub ws_url: String,
370    pub files: Vec<FileInfo>,
371    pub revisions: Vec<RevisionInfo>,
372    #[serde(default)]
373    pub meta: Value,
374}
375
376/// `PATCH /api/v1/docs/{id}`: change metadata without a new revision.
377#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
378pub struct PatchDoc {
379    #[serde(default, skip_serializing_if = "Option::is_none")]
380    pub title: Option<String>,
381    /// Replace the full tag set.
382    #[serde(default, skip_serializing_if = "Option::is_none")]
383    pub tags: Option<Vec<String>>,
384    #[serde(default, skip_serializing_if = "Vec::is_empty")]
385    pub add_tags: Vec<String>,
386    #[serde(default, skip_serializing_if = "Vec::is_empty")]
387    pub remove_tags: Vec<String>,
388    /// Merged into the stored meta object; `null` values remove keys.
389    #[serde(default, skip_serializing_if = "Option::is_none")]
390    pub meta: Option<Value>,
391}
392
393/// `GET /api/v1/docs/{id}/view`: a freshly signed content URL for the viewer.
394#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
395pub struct ViewResponse {
396    pub content_url: String,
397    pub rev: i64,
398    pub path: String,
399    #[serde(with = "time::serde::rfc3339")]
400    pub expires_at: OffsetDateTime,
401}
402
403#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
404pub struct UserInfo {
405    pub id: i64,
406    pub email: String,
407    pub display_name: String,
408    pub is_admin: bool,
409}
410
411#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
412pub struct KeyInfo {
413    pub id: i64,
414    pub name: String,
415    pub prefix: String,
416    pub scopes: Vec<Scope>,
417    pub created_via: String,
418    #[serde(with = "time::serde::rfc3339")]
419    pub created_at: OffsetDateTime,
420    #[serde(
421        default,
422        with = "time::serde::rfc3339::option",
423        skip_serializing_if = "Option::is_none"
424    )]
425    pub last_used_at: Option<OffsetDateTime>,
426    #[serde(
427        default,
428        with = "time::serde::rfc3339::option",
429        skip_serializing_if = "Option::is_none"
430    )]
431    pub expires_at: Option<OffsetDateTime>,
432    #[serde(
433        default,
434        with = "time::serde::rfc3339::option",
435        skip_serializing_if = "Option::is_none"
436    )]
437    pub revoked_at: Option<OffsetDateTime>,
438}
439
440#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
441pub struct WhoAmI {
442    pub server: String,
443    /// The id `.semora` files name this server by. `None` from a server older than this field.
444    #[serde(default, skip_serializing_if = "Option::is_none")]
445    pub server_id: Option<String>,
446    pub user: UserInfo,
447    #[serde(default, skip_serializing_if = "Option::is_none")]
448    pub key: Option<KeyInfo>,
449}
450
451#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
452pub struct CreateKeyRequest {
453    pub name: String,
454    #[serde(default, skip_serializing_if = "Option::is_none")]
455    pub scopes: Option<Vec<Scope>>,
456    #[serde(default, skip_serializing_if = "Option::is_none")]
457    pub expires_in_days: Option<u32>,
458}
459
460#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
461pub struct CreatedKey {
462    pub key: KeyInfo,
463    /// The full key. Its owner can also copy it later from the account page.
464    pub secret: String,
465}
466
467/// `POST /api/v1/cli/device`: the CLI asks to sign in.
468#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
469pub struct CliDeviceRequest {
470    /// Name for the key the sign-in creates, e.g. `cli@hostname`.
471    #[serde(default)]
472    pub name: String,
473}
474
475#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
476pub struct CliDeviceResponse {
477    /// The secret the CLI polls `/api/v1/cli/token` with. It never leaves the CLI.
478    pub device_code: String,
479    /// The short code the person checks in the browser, like `ABCD-EFGH`.
480    pub user_code: String,
481    /// The page that asks for the code.
482    pub verification_uri: String,
483    /// The same page with the code filled in.
484    pub verification_uri_complete: String,
485    /// Seconds until the sign-in is forgotten.
486    pub expires_in: u64,
487    /// Seconds to wait between polls.
488    pub interval: u64,
489}
490
491#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
492pub struct CliTokenRequest {
493    pub device_code: String,
494}
495
496/// What a poll of `/api/v1/cli/token` finds. `Approved` is answered once.
497#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
498#[serde(tag = "status", rename_all = "snake_case")]
499pub enum CliTokenResponse {
500    /// Nobody has decided yet; poll again.
501    Pending,
502    Approved {
503        api_key: String,
504        name: String,
505        user: UserInfo,
506    },
507    Denied,
508    /// Unknown, already used, or older than `expires_in`.
509    Expired,
510}
511
512#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
513pub struct ApiErrorBody {
514    pub error: String,
515    pub message: String,
516}
517
518// ---------------------------------------------------------------------------
519// Feedback events and websocket messages
520// ---------------------------------------------------------------------------
521
522#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
523#[serde(rename_all = "snake_case")]
524pub enum EventKind {
525    Comment,
526    Drawing,
527    PageEvent,
528    Message,
529    /// A message from an agent to the page. Stored for the feed, never delivered to agents.
530    Say,
531}
532
533impl EventKind {
534    pub fn as_str(self) -> &'static str {
535        match self {
536            EventKind::Comment => "comment",
537            EventKind::Drawing => "drawing",
538            EventKind::PageEvent => "page_event",
539            EventKind::Message => "message",
540            EventKind::Say => "say",
541        }
542    }
543
544    /// Kinds that come from the page and are delivered to agents.
545    pub fn feedback() -> [EventKind; 4] {
546        [
547            EventKind::Comment,
548            EventKind::Drawing,
549            EventKind::PageEvent,
550            EventKind::Message,
551        ]
552    }
553
554    pub fn parse_list(s: &str) -> Result<Vec<EventKind>, String> {
555        s.split(',')
556            .map(str::trim)
557            .filter(|p| !p.is_empty())
558            .map(EventKind::from_str)
559            .collect()
560    }
561}
562
563impl FromStr for EventKind {
564    type Err = String;
565    fn from_str(s: &str) -> Result<Self, Self::Err> {
566        match s {
567            "comment" => Ok(EventKind::Comment),
568            "drawing" => Ok(EventKind::Drawing),
569            "page_event" => Ok(EventKind::PageEvent),
570            "message" => Ok(EventKind::Message),
571            "say" => Ok(EventKind::Say),
572            other => Err(format!("unknown event kind `{other}`")),
573        }
574    }
575}
576
577impl fmt::Display for EventKind {
578    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
579        f.write_str(self.as_str())
580    }
581}
582
583/// Where a comment points: a W3C text-quote selector plus a CSS selector and
584/// the nearest heading, so an agent can find the spot without line numbers.
585#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
586pub struct Anchor {
587    pub path: String,
588    #[serde(default, skip_serializing_if = "Option::is_none")]
589    pub quote: Option<String>,
590    #[serde(default, skip_serializing_if = "Option::is_none")]
591    pub prefix: Option<String>,
592    #[serde(default, skip_serializing_if = "Option::is_none")]
593    pub suffix: Option<String>,
594    #[serde(default, skip_serializing_if = "Option::is_none")]
595    pub selector: Option<String>,
596    #[serde(default, skip_serializing_if = "Option::is_none")]
597    pub heading: Option<String>,
598}
599
600#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
601pub struct Size {
602    pub width: u32,
603    pub height: u32,
604}
605
606#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
607pub struct Point {
608    pub x: i64,
609    pub y: i64,
610}
611
612/// A stored feedback event as delivered to an agent.
613#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
614pub struct EventOut {
615    pub id: i64,
616    pub doc_id: String,
617    pub kind: EventKind,
618    pub rev: i64,
619    #[serde(default, skip_serializing_if = "Option::is_none")]
620    pub path: Option<String>,
621    pub payload: Value,
622    #[serde(default, skip_serializing_if = "Option::is_none")]
623    pub attachment_url: Option<String>,
624    #[serde(with = "time::serde::rfc3339")]
625    pub created_at: OffsetDateTime,
626    /// Who sent it. Absent when that account is gone.
627    #[serde(default, skip_serializing_if = "Option::is_none")]
628    pub from: Option<Person>,
629}
630
631/// A message from an agent shown in the page.
632#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
633pub struct SayOut {
634    pub id: i64,
635    pub text: String,
636    #[serde(default, skip_serializing_if = "Option::is_none")]
637    pub reply_to: Option<i64>,
638    #[serde(with = "time::serde::rfc3339")]
639    pub created_at: OffsetDateTime,
640    /// Who sent it. Absent when that account is gone.
641    #[serde(default, skip_serializing_if = "Option::is_none")]
642    pub from: Option<Person>,
643    /// Sent when a page connects, replaying recent messages for the feed.
644    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
645    pub backlog: bool,
646}
647
648/// A comment, drawing or message as the page's margin shows it.
649#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
650pub struct NoteOut {
651    pub event: EventOut,
652    /// The name of the first key that acked it. Absent while no agent has it.
653    #[serde(default, skip_serializing_if = "Option::is_none")]
654    pub delivered_to: Option<String>,
655    /// Sent when a page connects, replaying recent entries for the margin.
656    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
657    pub backlog: bool,
658}
659
660/// `POST /api/v1/docs/{id}/events`.
661#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
662pub struct SayRequest {
663    pub text: String,
664    #[serde(default, skip_serializing_if = "Option::is_none")]
665    pub reply_to: Option<i64>,
666}
667
668/// `GET /api/v1/docs/{id}/events`.
669#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
670pub struct EventsResponse {
671    pub events: Vec<EventOut>,
672}
673
674/// `POST /api/v1/docs/{id}/attachments`.
675#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
676pub struct AttachmentResponse {
677    pub attachment_id: String,
678}
679
680/// Messages sent by the server on a document channel.
681#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
682#[serde(tag = "type", rename_all = "snake_case")]
683pub enum ServerMsg {
684    Hello {
685        doc_id: String,
686        rev: i64,
687        agents: usize,
688        browsers: usize,
689    },
690    Revision {
691        rev: i64,
692        changed: Vec<String>,
693    },
694    Presence {
695        agents: usize,
696        browsers: usize,
697    },
698    Event(EventOut),
699    Say(SayOut),
700    /// To pages: a comment, drawing or message that someone at a page sent.
701    Note(NoteOut),
702    /// To pages: an agent's key acked the event `id`; `to` is the key's name.
703    Delivered {
704        id: i64,
705        to: String,
706    },
707    Error {
708        message: String,
709    },
710}
711
712/// Messages sent by browsers and agents on a document channel.
713#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
714#[serde(tag = "type", rename_all = "snake_case")]
715pub enum ClientMsg {
716    // Browser → server
717    Comment {
718        anchor: Anchor,
719        text: String,
720    },
721    Drawing {
722        path: String,
723        #[serde(default, skip_serializing_if = "Option::is_none")]
724        note: Option<String>,
725        attachment_id: String,
726        viewport: Size,
727        scroll: Point,
728    },
729    PageEvent {
730        name: String,
731        #[serde(default)]
732        data: Value,
733        #[serde(default, skip_serializing_if = "Option::is_none")]
734        path: Option<String>,
735    },
736    Message {
737        text: String,
738        #[serde(default, skip_serializing_if = "Option::is_none")]
739        path: Option<String>,
740    },
741    // Agent → server
742    Ack {
743        id: i64,
744    },
745    Say {
746        text: String,
747        #[serde(default, skip_serializing_if = "Option::is_none")]
748        reply_to: Option<i64>,
749    },
750}