instapi360_cloud/model.rs
1//! Wire and domain types for cloud media.
2//!
3//! The API wraps every response in an envelope `{ code, ... , data }`. Media
4//! items can be **multi-file** (an X5 dual-lens `.insv` is two files,
5//! `VID_..._00_*.insv` + `VID_..._10_*.insv`; an Ace Pro 2 clip is one). We
6//! model one logical [`Media`] as an asset owning a list of [`FilePart`]s.
7
8use serde::{Deserialize, Serialize};
9
10/// Standard response envelope. Insta360 has used both `code` and `errCode`
11/// across versions, and both `errInfo`/`msg` for the message; accept all.
12#[derive(Debug, Deserialize)]
13pub struct Envelope<T> {
14 #[serde(alias = "errCode")]
15 pub code: Option<i64>,
16 #[serde(alias = "errInfo", alias = "msg", alias = "message")]
17 pub message: Option<String>,
18 pub data: Option<T>,
19}
20
21impl<T> Envelope<T> {
22 /// `true` when the envelope reports success (`code` is 0 or absent).
23 pub fn is_ok(&self) -> bool {
24 self.code.unwrap_or(0) == 0
25 }
26}
27
28/// Opaque identifier for a cloud media item.
29#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
30pub struct MediaId(pub String);
31
32impl std::fmt::Display for MediaId {
33 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
34 f.write_str(&self.0)
35 }
36}
37
38/// Kind of media, derived from the API's `mediaType`.
39#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
40pub enum MediaKind {
41 /// 360 footage (`.insv`), single- or dual-lens.
42 Insv360,
43 /// Flat / standard video (`.mp4`).
44 FlatVideo,
45 /// Photo (`.insp`/`.jpg`/`.dng`).
46 Photo,
47 /// Unknown / not yet mapped.
48 Other,
49}
50
51/// One downloadable file belonging to a [`Media`]. For dual-lens 360 clips
52/// there are two of these.
53#[derive(Debug, Clone, Serialize, Deserialize)]
54pub struct FilePart {
55 /// Original filename, e.g. `VID_20250514_192854_00_005.insv`.
56 pub file_name: String,
57 /// Size in bytes as reported by the API (`fileSize`).
58 pub size: u64,
59 /// Signed download URL (Alibaba OSS). Short-lived — resolve just-in-time.
60 pub url: String,
61 /// Expected MD5 if the API provides one, for integrity checking.
62 pub md5: Option<String>,
63}
64
65/// A logical cloud media asset (may span multiple [`FilePart`]s).
66#[derive(Debug, Clone, Serialize, Deserialize)]
67pub struct Media {
68 pub id: MediaId,
69 /// Display / base name (`mediaName`).
70 pub name: String,
71 pub kind: MediaKind,
72 /// Original size in bytes summed across parts (`downOriginalSize`).
73 pub size_original: u64,
74 /// Capture time (unix seconds) if known (`mediaTime`/`create_time`).
75 pub time_unix: Option<i64>,
76 /// Camera model if the API reports it (`camera_name`).
77 pub camera: Option<String>,
78 /// The files that make up this asset.
79 pub parts: Vec<FilePart>,
80}
81
82/// One page of a media listing plus the cursor to fetch the next page.
83#[derive(Debug, Clone)]
84pub struct MediaPage {
85 pub items: Vec<Media>,
86 /// Total item count reported by the API (`totalCount`), if present.
87 pub total: Option<u64>,
88 /// Opaque cursor / next page token; `None` when there are no more pages.
89 pub next: Option<PageCursor>,
90}
91
92/// Pagination request cursor.
93#[derive(Debug, Clone, Default)]
94pub struct PageCursor {
95 /// Page index (1-based) or offset, depending on the endpoint.
96 pub page: u32,
97 /// Page size.
98 pub count: u32,
99}
100
101impl PageCursor {
102 pub fn first(count: u32) -> Self {
103 PageCursor { page: 1, count }
104 }
105 pub fn next(&self) -> Self {
106 PageCursor {
107 page: self.page + 1,
108 count: self.count,
109 }
110 }
111}
112
113/// Authenticated account profile (subset we need).
114#[derive(Debug, Clone, Deserialize)]
115pub struct Profile {
116 #[serde(alias = "userId", alias = "ins_user_id")]
117 pub user_id: Option<String>,
118 #[serde(alias = "userEmail", alias = "email")]
119 pub email: Option<String>,
120 #[serde(alias = "userName", alias = "username", alias = "nickname")]
121 pub name: Option<String>,
122}