Skip to content

Native iCloud apps for Windows and Linux, built in Rust. Notes, Reminders, Calendar, Contacts, Drive and Photos, offline and in sync with your iPhone.

Drive: Recents backend (docws list/recents, verified live read-only); download takes the item for files outside synced folders

Yashwanth Kamireddicd2d7ec036cb
diff --git a/crates/quince-icloud/src/drive.rs b/crates/quince-icloud/src/drive.rs
index 08b779b..de9d4d2 100644
--- a/crates/quince-icloud/src/drive.rs
+++ b/crates/quince-icloud/src/drive.rs
@@ -548,6 +548,68 @@ pub struct TrashItem {
pub restore_path: Option<String>,
}
+/// A file in Recents, with when it was last opened.
+#[derive(Debug, Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RecentItem {
+ #[serde(flatten)]
+ pub item: DriveItem,
+ /// Unix seconds.
+ pub opened_at: Option<i64>,
+}
+
+/// The files opened most recently, newest first, as icloud.com's Recents lists them. Read
+/// from the document service (`docws`), not the folder one. Read-only.
+pub async fn recents(
+ http: &reqwest::Client,
+ docws_root: &str,
+ params: Vec<(String, String)>,
+) -> Result<Vec<RecentItem>> {
+ let mut query = params;
+ query.push(("limit".into(), "50".into()));
+ query.push(("unified_format".into(), "true".into()));
+ let url = format!(
+ "{}/ws/com.apple.CloudDocs/list/recents",
+ docws_root.trim_end_matches('/')
+ );
+ let response = http.get(url).query(&query).send().await?;
+ let status = response.status();
+ if status.as_u16() == 450 {
+ return Err(Error::ReauthRequired);
+ }
+ let text = response.text().await.unwrap_or_default();
+ if !status.is_success() {
+ return Err(Error::Protocol(format!(
+ "Drive returned {status}: {}",
+ text.chars().take(160).collect::<String>()
+ )));
+ }
+ let parsed: Value = serde_json::from_str(&text)
+ .map_err(|e| Error::Protocol(format!("Drive returned invalid JSON: {e}")))?;
+ Ok(parse_recents(&parsed))
+}
+
+/// The documents of a `list/recents` answer, newest opened first.
+#[must_use]
+pub fn parse_recents(body: &Value) -> Vec<RecentItem> {
+ let mut out: Vec<RecentItem> = body
+ .get("documents")
+ .and_then(Value::as_array)
+ .map(|docs| {
+ docs.iter()
+ .filter_map(|d| {
+ Some(RecentItem {
+ item: item_from(d)?,
+ opened_at: seconds(d, "lastOpenTime"),
+ })
+ })
+ .collect()
+ })
+ .unwrap_or_default();
+ out.sort_by_key(|r| std::cmp::Reverse(r.opened_at));
+ out
+}
+
/// What is in Recently Deleted now. Read-only.
pub async fn trash(
http: &reqwest::Client,
@@ -2158,3 +2220,20 @@ mod storage_tests {
);
}
}
+
+#[cfg(test)]
+mod recents_tests {
+ #[test]
+ fn recents_are_read_newest_opened_first() {
+ let body = serde_json::json!({ "documents": [
+ { "drivewsid": "FILE::z::a", "name": "Old", "extension": "pdf", "type": "FILE", "size": 10, "lastOpenTime": "2026-10-01T10:00:00Z" },
+ { "drivewsid": "FILE::z::b", "name": "New", "extension": "pdf", "type": "FILE", "size": 20, "lastOpenTime": "2026-10-16T18:46:11Z" },
+ ]});
+ let got = super::parse_recents(&body);
+ assert_eq!(
+ got.iter().map(|r| r.item.name.as_str()).collect::<Vec<_>>(),
+ ["New", "Old"]
+ );
+ assert_eq!(got[0].opened_at, Some(1_792_176_371));
+ }
+}
diff --git a/probe/examples/drive_recents.rs b/probe/examples/drive_recents.rs
new file mode 100644
index 0000000..08d0eee
--- /dev/null
+++ b/probe/examples/drive_recents.rs
@@ -0,0 +1,28 @@
+//! Read-only: Drive's Recents, as icloud.com asks for them.
+use anyhow::{anyhow, Result};
+#[tokio::main]
+async fn main() -> Result<()> {
+ let dir = std::path::PathBuf::from(std::env::var("HOME")?).join(".local/share/quince-probe");
+ let mut client = quince_auth::Client::new(&dir)?;
+ if !client.resume().await? {
+ return Err(anyhow!("no session"));
+ }
+ let root = client
+ .session()
+ .service_url("docws")
+ .ok_or_else(|| anyhow!("no docws"))?;
+ let (http, mut p) = (client.http().clone(), client.service_params());
+ p.push(("limit".into(), "50".into()));
+ p.push(("unified_format".into(), "true".into()));
+ for app in ["com.apple.CloudDocs", "_all_"] {
+ let url = format!("{}/ws/{app}/list/recents", root.trim_end_matches('/'));
+ let r = http.get(&url).query(&p).send().await?;
+ let status = r.status();
+ let text = r.text().await?;
+ println!(
+ "{app}: {status} {}",
+ text.chars().take(1500).collect::<String>()
+ );
+ }
+ Ok(())
+}
diff --git a/src-tauri/src/main.rs b/src-tauri/src/main.rs
index 4ecddbb..8e4e0fe 100644
--- a/src-tauri/src/main.rs
+++ b/src-tauri/src/main.rs
@@ -1743,17 +1743,20 @@ async fn resync_drive_folder(
#[tauri::command]
async fn drive_download(
drivewsid: String,
+ item: Option<quince_core::drive::DriveItem>,
app: tauri::AppHandle,
auth: State<'_, Auth>,
data: State<'_, Data>,
) -> UiResult<String> {
- let item = {
+ // A file seen only in Recents was never in a folder this library has read, so the item
+ // comes with the request; the library's own copy wins when there is one.
+ let stored = {
let library = data.0.lock().await;
- library
- .drive_item(&drivewsid)
- .map_err(|e| e.to_string())?
- .ok_or("That item is no longer in the local library.")?
+ library.drive_item(&drivewsid).map_err(|e| e.to_string())?
};
+ let item = stored
+ .or(item.filter(|i| i.drivewsid == drivewsid))
+ .ok_or("That item is no longer in the local library.")?;
if item.is_container() {
return Err("That's a folder, not a file.".into());
}
@@ -2285,6 +2288,22 @@ async fn drive_trash(auth: State<'_, Auth>) -> UiResult<Vec<quince_icloud::drive
.map_err(|e| e.to_string())
}
+/// The files opened most recently, newest first — Drive's Recents.
+#[tauri::command]
+async fn drive_recents(auth: State<'_, Auth>) -> UiResult<Vec<quince_icloud::drive::RecentItem>> {
+ let (http, root, params) = {
+ let client = auth.client.lock().await;
+ let root = client
+ .session()
+ .service_url("docws")
+ .ok_or("Apple hasn't offered Recents for this account.")?;
+ (client.http().clone(), root, client.service_params())
+ };
+ quince_icloud::drive::recents(&http, &root, params)
+ .await
+ .map_err(|e| e.to_string())
+}
+
/// Recover an item from Recently Deleted to where it was.
#[tauri::command]
async fn drive_put_back(
@@ -2758,6 +2777,7 @@ fn main() {
drive_rename,
drive_delete,
drive_trash,
+ drive_recents,
storage_info,
drive_duplicate,
drive_thumbnails,
diff --git a/src/lib/ipc.ts b/src/lib/ipc.ts
index b8d6cc2..b55a1e2 100644
--- a/src/lib/ipc.ts
+++ b/src/lib/ipc.ts
@@ -179,7 +179,9 @@ export const api = {
driveChildren: (folderId: string) => invoke<DriveItem[]>("drive_children", { folderId }),
driveItem: (drivewsid: string) => invoke<DriveItem | null>("drive_item", { drivewsid }),
/** Saves to Downloads; returns the path it landed at. */
- driveDownload: (drivewsid: string) => invoke<string>("drive_download", { drivewsid }),
+ driveDownload: (drivewsid: string, item?: DriveItem) => invoke<string>("drive_download", { drivewsid, item: item ?? null }),
+ /** The files opened most recently, newest first. */
+ driveRecents: () => invoke<RecentItem[]>("drive_recents"),
/**
* Put files from this machine into a Drive folder. Paths only — the bytes are read and
* streamed in the backend, never carried through a message.
@@ -433,6 +435,8 @@ export type ContactList = {
};
/** Which events a change to one day of a repeating event is for. */
+export type RecentItem = DriveItem & { openedAt: number | null };
+
export type EventScope = "this" | "future" | "all";
export type Contact = {