jmap-chat-client 0.1.2

JMAP Chat HTTP client — auth-agnostic, WebSocket and SSE support
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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

//! Display-formatting helpers for JMAP Chat clients.

use chrono::{DateTime, Datelike, Timelike, Utc};

use jmap_types::UTCDate;

/// Format a receipt timestamp without exposing sub-minute precision.
///
/// Returns a human-readable relative string:
/// - Same calendar day as now (or future): `"Today"`
/// - Previous calendar day: `"Yesterday"`
/// - 2–6 days ago: `"Mon 14:00"` (weekday abbreviation + HH:MM)
/// - Same year, older than 6 days: `"Apr 12"` (month abbreviation + day number)
/// - Different year: `"Apr 12 2023"` (month + day + year)
/// - Unparsable input: raw string returned unchanged
///
/// **UTC dates only.** Both `dt` and the implicit current time are treated as
/// UTC wall-clock dates. Callers in non-UTC time zones that need local-day
/// semantics should use [`format_receipt_timestamp_at`] with a local-adjusted
/// reference time.
///
/// **Stability note**: The exact output strings (`"Today"`, `"Jan 15"`, etc.)
/// are informational display strings, not a stable API contract.
pub fn format_receipt_timestamp(dt: &UTCDate) -> String {
    let now_str = Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true);
    let now = UTCDate::from(now_str.as_str());
    format_receipt_timestamp_at(dt, &now)
}

/// Like [`format_receipt_timestamp`] but accepts an explicit reference time,
/// allowing deterministic unit tests and caller-managed timezone offset.
///
/// Both `dt` and `now` are treated as UTC. To display in local time, adjust
/// `now` to the desired reference point before calling.
///
/// `now` is typed as [`UTCDate`] (a JMAP-native String newtype, RFC 3339)
/// rather than `chrono::DateTime<chrono::Utc>` so the public signature
/// of this crate does not leak the `chrono` major-version into its
/// SemVer surface. The implementation parses `now` internally and
/// silently falls back to "Today" if the reference time is itself
/// unparsable (matching the existing behaviour for `dt`).
pub fn format_receipt_timestamp_at(dt: &UTCDate, now: &UTCDate) -> String {
    let parsed = match chrono::DateTime::parse_from_rfc3339(dt.as_ref()) {
        Ok(d) => d.with_timezone(&Utc),
        Err(_) => return dt.as_ref().to_string(),
    };

    // Parse the reference time. If it itself fails to parse (callers
    // typically supply a fresh Utc::now() via the public free function
    // above, so this is rare), fall back to treating `dt` as "Today".
    let now: DateTime<Utc> = match chrono::DateTime::parse_from_rfc3339(now.as_ref()) {
        Ok(d) => d.with_timezone(&Utc),
        Err(_) => return "Today".to_string(),
    };

    let dt_date = parsed.date_naive();
    let now_date = now.date_naive();
    let days_diff = (now_date - dt_date).num_days();

    // Negative days_diff means dt is in the future (clock skew); treat as today.
    match days_diff {
        ..=0 => "Today".to_string(),
        1 => "Yesterday".to_string(),
        2..=6 => {
            // chrono's %a is locale-independent: short English weekday
            // name (Mon, Tue, Wed, Thu, Fri, Sat, Sun) regardless of
            // the host OS locale — matching the prior hand-rolled
            // table byte-for-byte while delegating to chrono's tested
            // implementation.
            format!(
                "{} {:02}:{:02}",
                parsed.format("%a"),
                parsed.hour(),
                parsed.minute()
            )
        }
        _ => {
            // %b is the locale-independent short month name (Jan, Feb,
            // ..., Dec). Same byte-equivalent guarantee as %a above.
            if parsed.year() != now.year() {
                format!("{} {} {}", parsed.format("%b"), parsed.day(), parsed.year())
            } else {
                format!("{} {}", parsed.format("%b"), parsed.day())
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Fixed reference time: 2024-03-20T15:00:00Z (Wednesday). Returned
    /// as `UTCDate` rather than `chrono::DateTime<Utc>` so the test
    /// suite does not depend on the `chrono` constructor API.
    fn now() -> UTCDate {
        UTCDate::from("2024-03-20T15:00:00Z")
    }

    /// Oracle: timestamp 2h before now (2024-03-20T13:00:00Z) — same calendar day → "Today".
    #[test]
    fn format_today() {
        let dt = UTCDate::from("2024-03-20T13:00:00Z");
        assert_eq!(format_receipt_timestamp_at(&dt, &now()), "Today");
    }

    /// Oracle: timestamp 25h before now (2024-03-19T14:00:00Z) — previous calendar day → "Yesterday".
    #[test]
    fn format_yesterday() {
        let dt = UTCDate::from("2024-03-19T14:00:00Z");
        assert_eq!(format_receipt_timestamp_at(&dt, &now()), "Yesterday");
    }

    /// Oracle: timestamp 3 days ago (2024-03-17T08:30:00Z — Sunday) → "Sun 08:30".
    #[test]
    fn format_this_week() {
        let dt = UTCDate::from("2024-03-17T08:30:00Z");
        assert_eq!(format_receipt_timestamp_at(&dt, &now()), "Sun 08:30");
    }

    /// Oracle: timestamp 8 days ago (2024-03-12T09:00:00Z) — same year → "Mar 12".
    ///
    /// Note: the bead spec says "DD/MM/YY" but the reference implementation uses
    /// "Mon DD" (month abbreviation + day), which is more readable and consistent
    /// with the rest of the formatting logic. The reference is authoritative.
    #[test]
    fn format_old() {
        let dt = UTCDate::from("2024-03-12T09:00:00Z");
        assert_eq!(format_receipt_timestamp_at(&dt, &now()), "Mar 12");
    }

    /// Oracle: unparsable string → returned unchanged (never panics).
    #[test]
    fn format_parse_error() {
        let dt = UTCDate::from("not-a-date");
        assert_eq!(format_receipt_timestamp_at(&dt, &now()), "not-a-date");
    }

    /// Oracle: prior year (2023-01-15) includes the year → "Jan 15 2023".
    #[test]
    fn format_prior_year() {
        let dt = UTCDate::from("2023-01-15T09:00:00Z");
        assert_eq!(format_receipt_timestamp_at(&dt, &now()), "Jan 15 2023");
    }

    /// Oracle: future timestamp (clock skew, dt > now) formats as "Today".
    #[test]
    fn format_future_clock_skew() {
        let dt = UTCDate::from("2024-03-21T10:00:00Z");
        assert_eq!(
            format_receipt_timestamp_at(&dt, &now()),
            "Today",
            "future timestamp must display as Today, not as a past date"
        );
    }

    /// Oracle: unparsable `now` reference time → fallback to "Today".
    /// This codifies the silent-degradation behaviour documented on
    /// the public function and locks it against accidental regression
    /// to a panic-on-malformed-now path.
    #[test]
    fn format_parse_error_on_now() {
        let dt = UTCDate::from("2024-03-20T13:00:00Z");
        let bad_now = UTCDate::from("not-a-date");
        assert_eq!(format_receipt_timestamp_at(&dt, &bad_now), "Today");
    }
}