Metadata-Version: 2.3
Name: icloud-resolver
Version: 0.1.0
Summary: Add your description here
Author: xxanqw
Author-email: xxanqw <potik217@gmail.com>
Requires-Dist: requests>=2.34.2
Requires-Dist: tqdm>=4.67.3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# iCloud Resolver

A fast and lightweight Python library and CLI tool to securely resolve and download files from iCloud Drive public links.

## How it works

When you share a public iCloud Drive link (e.g., `https://www.icloud.com/iclouddrive/...`), it is not a direct file download link. Instead, it leads to Apple's web application.

This tool bypasses the browser by interacting directly with Apple's public **CloudKit API**. It parses the unique identifier from the link, queries the iCloud database, and safely retrieves the original filename along with the highly-secure, direct `downloadURL`. Finally, it streams the file directly to your disk with a progress bar.

*(Note: iCloud Drive folders are currently not supported because downloading them requires user authentication and dynamic zip archiving).*

---

## Command Line Interface (CLI)

You can run this tool instantly from your terminal using zero-install execution tools like `uvx` or `pipx`:

```bash
# Using uvx
uvx icloud-resolver "https://www.icloud.com/iclouddrive/0afGK6zDBog_0drwp6YZoDLIg#Patches"

# Using pipx
pipx run icloud-resolver "https://www.icloud.com/iclouddrive/0afGK6zDBog_0drwp6YZoDLIg#Patches"
```

If you install the package globally (e.g. `uv tool install .`), it exposes two aliases that you can use interchangeably: `icloud-resolver` and the shorter `icr`.

### CLI Options

*   **Download to the current directory:**
    ```bash
    icr "https://www.icloud.com/iclouddrive/..."
    ```

*   **Specify an output directory or custom file name:**
    ```bash
    icr -o ./my_downloads "https://www.icloud.com/iclouddrive/..."
    icr -o custom_file.zip "https://www.icloud.com/iclouddrive/..."
    ```

*   **Only resolve the URL (print the direct download link without downloading):**
    ```bash
    icr -r "https://www.icloud.com/iclouddrive/..."
    ```

---

## Programmatic Usage

You can also import `icloud-resolver` directly into your own Python scripts. The library features robust custom exceptions for smooth programmatic error handling.

### `example.py`

```python
from icloud_resolver import resolve_icloud_link, download_file
from icloud_resolver.exceptions import (
    ICloudResolverError, 
    FolderNotSupportedError
)

url = "https://www.icloud.com/iclouddrive/0afGK6zDBog_0drwp6YZoDLIg#Patches"

# Example 1: Resolving the link without downloading
try:
    direct_url, filename = resolve_icloud_link(url)
    print(f"Original Name: {filename}")
    print(f"Direct Link: {direct_url}")
except FolderNotSupportedError:
    print("Oops! This link points to a folder, which is unsupported.")
except ICloudResolverError as e:
    print(f"Something went wrong: {e}")

# Example 2: Downloading the file directly
try:
    # Set target_path to a directory to auto-use the original filename, 
    # or set it to a full path to use a custom filename.
    saved_path = download_file(url, target_path=".")
    print(f"File successfully downloaded to: {saved_path}")
except ICloudResolverError as e:
    print(f"Download failed: {e}")
```
