Skip to main content

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}