cloudapp-dl/README.md

CloudApp/Zight API client and CLI. Use as a CLI tool to download videos or as a programmatic library to interact with the Zight API.

# CloudApp/Zight Downloader

A powerful Node.js package to download, upload, and manage files on Zight (formerly CloudApp). Use it as a **CLI tool** or as a **programmatic library** in your Node.js projects.

## Features

- ✨ **Dual Mode** - Use as CLI tool or import as a library in your projects
- 📂 **List Drops** - View and browse your files with pagination
- 📊 **Export to CSV** - Export your entire library metadata to a CSV file
- ⬇️ **Flexible Downloads** - Download by ID, URL, from a list file, or bulk from your account
- ⬆️ **Upload Files** - Upload single files or entire directories
- 🗑️ **Delete & Trash** - Delete files, view trash, restore items, or permanently delete
- 🎬 **Video Filtering** - Option to download only video files
- 📹 **Video Requests** - Create, list, edit, and delete video request links
- 📁 **Collections** - View your collections
- 🔔 **Notifications** - View and manage notifications
- 🔄 **Auto Session Refresh** - Sessions auto-refresh when expired
- 🔐 **Secure Config** - Credentials stored securely in your OS config directory
- ⏱️ **Rate Limiting** - Built-in delays between requests to avoid being blocked

## Installation

### Via NPM (Recommended)

```bash
npm install -g cloudapp-dl
```

### From Source

```bash
git clone https://github.com/EcomGraduates/cloudapp-downloader.git
cd cloudapp-downloader
npm install
npm link  # Makes 'cloudapp-dl' available globally
```

---

## Using as a Library

You can import and use `cloudapp-dl` as a programmatic library in your Node.js projects.

### Quick Start (ESM)

```javascript
import { ZightClient } from 'cloudapp-dl';

// Create client with email/password
const client = new ZightClient({
  email: 'your@email.com',
  password: 'your-password'
});

// Login
await client.login();

// Use the API
const account = await client.getAccountDetails();
console.log('Logged in as:', account.data.user.attributes.email);
```

### Quick Start (CommonJS)

```javascript
const { ZightClient } = require('cloudapp-dl');

async function main() {
  const client = new ZightClient({
    email: 'your@email.com',
    password: 'your-password'
  });

  await client.login();
  
  const account = await client.getAccountDetails();
  console.log('Logged in as:', account.data.user.attributes.email);
}

main();
```

### Authentication Options

```javascript
// Option 1: Email/Password (will call login() to authenticate)
const client = new ZightClient({
  email: process.env.ZIGHT_EMAIL,
  password: process.env.ZIGHT_PASSWORD
});
await client.login();

// Option 2: Existing Session ID (skip login if you already have a session)
const client = new ZightClient({
  sessionId: 'your-existing-session-id'
});
```

### Debug Mode

Enable debug logging to see what's happening under the hood:

```javascript
const client = new ZightClient({
  email: 'your@email.com',
  password: 'your-password',
  debug: true  // Enables debug logging
});
```

### Available Methods

#### Account & Info

```javascript
// Get account details
const account = await client.getAccountDetails();

// Get organization details
const org = await client.getOrganization();

// Check authentication status
console.log('Authenticated:', client.isAuthenticated);
console.log('Session ID:', client.sessionId);
```

#### Files & Items

```javascript
// List items (paginated)
const items = await client.getItemsFromDashboard({ page: 1, perPage: 24 });

// Get all items
const allItems = await client.getAllItems();

// Get a specific item
const item = await client.getItem('itemId');

// Search items
const results = await client.searchDrops('search query');

// Get drops (files)
const drops = await client.getDrops({ page: 1, perPage: 20 });
```

#### Upload & Download

```javascript
// Upload a file
const result = await client.uploadFile('./screenshot.png');
console.log('Share URL:', result.share_url);

// Upload with progress callback
const result = await client.uploadFile('./video.mp4', (progress) => {
  const percent = Math.round((progress.loaded / progress.total) * 100);
  console.log(`Upload progress: ${percent}%`);
});

// Get download URL for an item
const item = await client.getItem('itemId');
console.log('Download URL:', item.download_url);
```

#### Delete & Trash

```javascript
// Delete an item (move to trash)
await client.deleteItem('itemId');

// Permanently delete an item
await client.deleteItem('itemId', true);

// List items in trash
const trashItems = await client.getTrashItems();

// Restore an item from trash
await client.restoreItem('itemId');

// Empty trash
await client.emptyTrash();
```

#### Video Requests

```javascript
// Create a video request link
const request = await client.createVideoRequest({
  name: 'Help me with this bug',
  message: 'Please record your screen showing the issue'
});
console.log('Share link:', request.data.request_content.links.request_link);

// List all video requests
const requests = await client.getVideoRequests();

// Get a specific request
const req = await client.getVideoRequest('requestId');

// Update a request
await client.updateVideoRequest('requestId', {
  name: 'Updated Title',
  message: 'Updated instructions'
});

// Delete a request
await client.deleteVideoRequest('requestId');
```

#### Collections

```javascript
// List collections
const collections = await client.getCollections();

// Get all collections
const allCollections = await client.getAllCollections();
```

#### Notifications

```javascript
// Get notifications
const notifications = await client.getNotifications({ limit: 10 });

// Get unread notifications
const unread = await client.getNotifications({ viewed: 'no', limit: 20 });

// Mark a notification as read
await client.markNotificationViewed('notificationId');

// Mark all notifications as read
await client.markAllNotificationsViewed();
```

### Full Example

```javascript
import { ZightClient } from 'cloudapp-dl';

async function main() {
  // Initialize client
  const client = new ZightClient({
    email: process.env.ZIGHT_EMAIL,
    password: process.env.ZIGHT_PASSWORD,
    debug: false
  });

  // Login
  await client.login();
  console.log('Logged in successfully!');

  // Get account info
  const account = await client.getAccountDetails();
  const user = account.data.user;
  console.log(`Welcome, ${user.attributes.name}!`);
  console.log(`You have ${user.attributes.item_count} items.`);

  // Upload a file
  const uploadResult = await client.uploadFile('./screenshot.png');
  console.log('Uploaded:', uploadResult.share_url);

  // Create a video request
  const request = await client.createVideoRequest({
    name: 'Support Request',
    message: 'Please record your screen showing the issue'
  });
  console.log('Request link:', request.data.request_content.links.request_link);

  // List recent items
  const items = await client.getItemsFromDashboard({ page: 1, perPage: 12 });
  console.log(`Recent items: ${items.items.length}`);

  // Get notifications
  const notifications = await client.getNotifications({ limit: 5 });
  console.log(`Notifications: ${notifications.data.client_notifications.length}`);
}

main().catch(console.error);
```

### Demo Scripts

Check out the `demo/` directory for example scripts:

```bash
cd demo
cp env.example .env
# Edit .env with your credentials

npm install dotenv
node demo.js              # Run all demos
node demo.js upload ./file.png
node demo.js create-request
node demo.js notifications
```

---

## CLI Usage

## Commands Overview

```
cloudapp-dl login                  Login to your Zight account
cloudapp-dl logout                 Logout and clear session
cloudapp-dl account                Display your Zight account details
cloudapp-dl whoami                 Show current login status
cloudapp-dl config                 View or manage configuration

cloudapp-dl list                   List your drops/files from Zight
cloudapp-dl export                 Export items to CSV file
cloudapp-dl collections            List your collections

cloudapp-dl get <id>               Download a single file by ID
cloudapp-dl download <url>         Download a single file by URL
cloudapp-dl download-list <file>   Download multiple files from a URL list
cloudapp-dl bulk-download          Bulk download files from your account

cloudapp-dl upload <file>          Upload a file to Zight
cloudapp-dl bulk-upload <path>     Upload multiple files from a directory

cloudapp-dl delete <id>            Delete a file (move to trash)
cloudapp-dl trash                  List items in trash
cloudapp-dl restore <id>           Restore a file from trash
cloudapp-dl empty-trash            Permanently delete all trash items

cloudapp-dl request                Create a video request (interactive)
cloudapp-dl request-quick          Instantly create a video request
cloudapp-dl requests               List your video requests
cloudapp-dl request-details <id>   View request details and submitted items
cloudapp-dl request-download <id>  Download all items from a request
cloudapp-dl request-edit <id>      Edit a video request
cloudapp-dl request-delete <id>    Delete a video request

cloudapp-dl help                   Show help information
```

## Account Commands

### Login to Your Account

```bash
cloudapp-dl login
```

You'll be prompted for your email and password. Credentials are stored locally for future sessions.

You can also provide credentials directly:

```bash
cloudapp-dl login --email your@email.com --password yourpassword
```

### View Account Details

```bash
cloudapp-dl account
```

Displays your account information including name, email, item count, and plan details.

### Check Login Status

```bash
cloudapp-dl whoami
```

Quick check of your current login status and session validity.

### Logout

```bash
cloudapp-dl logout
```

Clears your session (credentials remain stored for easy re-login).

### Configuration

View your current configuration:

```bash
cloudapp-dl config
```

Show config file path:

```bash
cloudapp-dl config --path
```

Clear all configuration data:

```bash
cloudapp-dl config --clear
```

## Listing & Exporting

### List Your Drops

```bash
cloudapp-dl list
```

Lists your drops/files from Zight. Supports pagination:

```bash
cloudapp-dl list --page 2 --per-page 48
```

### List Your Collections

```bash
cloudapp-dl collections
```

Displays all your collections with their IDs, names, item counts, and view counts.

### Export to CSV

Export all your items to a CSV file:

```bash
cloudapp-dl export
```

Export specific pages:

```bash
cloudapp-dl export --start-page 1 --end-page 10
```

Export to a specific file:

```bash
cloudapp-dl export --out my-export.csv
```

**CSV Columns:**
- `#` - Row number
- `ID` - Zight file ID
- `Title` - File name/title
- `Type` - File extension (.mp4, .png, .zip, etc.)
- `Views` - View count
- `Date` - Creation date
- `URL` - Share URL
- `Is Video` - Yes/No
- `Thumbnail` - Thumbnail URL

## Downloading Files

### Download by ID

Download a file using its Zight ID:

```bash
cloudapp-dl get WnuPyJR5
```

Download to specific directory:

```bash
cloudapp-dl get WnuPyJR5 --out ./downloads
```

Use ID as filename instead of title:

```bash
cloudapp-dl get WnuPyJR5 --no-title
```

### Download by URL

Download a file using its full URL:

```bash
cloudapp-dl download https://share.zight.com/WnuPyJR5
```

Download to specific directory:

```bash
cloudapp-dl download https://share.zight.com/WnuPyJR5 --out ./downloads
```

### Download from URL List

Create a text file with one URL per line (`urls.txt`):

```
https://share.zight.com/ABC123
https://share.zight.com/DEF456
https://share.zight.com/GHI789
```

Then download all of them:

```bash
cloudapp-dl download-list urls.txt
```

With options:

```bash
cloudapp-dl download-list urls.txt --out ./videos --prefix video --timeout 5000
```

### Bulk Download from Account

Download ALL files from your logged-in account:

```bash
cloudapp-dl bulk-download
```

With options:

```bash
cloudapp-dl bulk-download --out ./my-files --limit 50 --videos-only
```

Download specific pages:

```bash
cloudapp-dl bulk-download --start-page 1 --end-page 10
```

## Uploading Files

### Upload a Single File

```bash
cloudapp-dl upload ./video.mp4
```

```bash
cloudapp-dl upload ~/Desktop/screenshot.png
```

### Bulk Upload from Directory

Upload all files in a directory:

```bash
cloudapp-dl bulk-upload ./screenshots/
```

With custom delay between uploads:

```bash
cloudapp-dl bulk-upload ./videos/ --timeout 3000
```

### Supported File Types

The uploader automatically detects MIME types:

| Category | Extensions |
|----------|------------|
| **Video** | .mp4, .mov, .avi, .webm, .mkv, .m4v |
| **Images** | .png, .jpg, .jpeg, .gif, .webp, .svg, .bmp |
| **Audio** | .mp3, .wav, .ogg, .m4a |
| **Documents** | .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv |
| **Archives** | .zip, .rar, .7z, .tar, .gz |

## Deleting Files & Trash

### Delete a File (Move to Trash)

Delete a file by moving it to trash (recoverable for 30 days):

```bash
cloudapp-dl delete WnuPyJR5
```

Skip confirmation:

```bash
cloudapp-dl delete WnuPyJR5 --yes
```

### Permanently Delete

Permanently delete a file (no recovery):

```bash
cloudapp-dl delete WnuPyJR5 --permanent
```

⚠️ **Warning:** Permanent deletion cannot be undone!

### View Trash

List all items in your trash:

```bash
cloudapp-dl trash
```

Shows item ID, name, created date, and deleted date.

### Restore from Trash

Restore a file from trash:

```bash
cloudapp-dl restore WnuPyJR5
```

### Empty Trash

Permanently delete ALL items in trash:

```bash
cloudapp-dl empty-trash
```

Skip confirmation:

```bash
cloudapp-dl empty-trash --yes
```

## Video Requests

Create shareable links that allow others to record videos for you. The recordings will automatically appear in your Zight account.

### Create Request (Interactive)

```bash
cloudapp-dl request
```

This will guide you through:
1. Title for the request
2. Message/instructions for the recorder
3. Optional custom ID
4. Optional expiration date
5. Optional collection to save recordings to

### Create Request (Quick)

Instantly create a request with defaults:

```bash
cloudapp-dl request-quick
```

With options:

```bash
cloudapp-dl request-quick -t "Help me debug" --custom-id "TICKET-123"
```

### Create Request (With Options)

```bash
cloudapp-dl request \
  --title "Bug Report" \
  --message "Record your screen showing the bug" \
  --custom-id "TICKET-123" \
  --expires "12/31/2025 5:00pm" \
  --collection Y2foRdo
```

### List All Requests

```bash
cloudapp-dl requests
```

Show with full links:

```bash
cloudapp-dl requests --verbose
```

### View Request Details & Items

View a request and all items submitted to it:

```bash
cloudapp-dl request-details wgsX51
```

With download URLs:

```bash
cloudapp-dl request-details wgsX51 --verbose
```

### Download Items from a Request

Download all videos/files submitted to a request:

```bash
cloudapp-dl request-download wgsX51
```

With options:

```bash
cloudapp-dl request-download wgsX51 --out ./submissions --timeout 3000
```

### Edit a Request

```bash
cloudapp-dl request-edit ABC123 --title "New Title"
```

Edit multiple fields:

```bash
cloudapp-dl request-edit ABC123 \
  --title "Updated Title" \
  --message "New instructions" \
  --expires "12/31/2025 5:00pm"
```

Remove expiration:

```bash
cloudapp-dl request-edit ABC123 --expires never
```

Change collection:

```bash
cloudapp-dl request-edit ABC123 --collection Y2foRdo
```

### Delete a Request

```bash
cloudapp-dl request-delete ABC123
```

Skip confirmation:

```bash
cloudapp-dl request-delete ABC123 --yes
```

### Date Format for Expiration

The expiration date accepts multiple formats:
- `12/31/2025 5:00pm`
- `12/31/2025 17:00`
- `2025-12-31 5:00pm`
- `12/31/2025` (expires at end of day)

## Options Reference

### Global Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--help` | `-h` | Show help |
| `--version` | `-v` | Show version |

### List Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--page` | | Page number (default: 1) |
| `--per-page` | | Items per page - multiples of 12 (default: 12) |

### Export Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--out` | `-o` | Output CSV file path |
| `--start-page` | | Start from this page |
| `--end-page` | | End at this page |

### Download Options (get, download)

| Option | Alias | Description |
|--------|-------|-------------|
| `--out` | `-o` | Output path/directory |
| `--no-title` | | Use file ID as filename instead of title |

### Download List Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--out` | `-o` | Output directory |
| `--prefix` | `-p` | Filename prefix (e.g., "video" → video-1.mp4) |
| `--timeout` | `-t` | Delay between downloads in ms (default: 2000) |

### Bulk Download Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--out` | `-o` | Output directory (default: ./downloads) |
| `--start-page` | | Start from this page |
| `--end-page` | | End at this page |
| `--limit` | | Maximum number of files to download |
| `--videos-only` | | Only download video files |
| `--timeout` | `-t` | Delay between downloads in ms (default: 2000) |
| `--no-title` | | Use file IDs as filenames instead of titles |

### Upload Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--timeout` | `-t` | Delay between uploads in ms (default: 2000) - bulk-upload only |

### Delete Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--permanent` | | Permanently delete (no recovery) |
| `--yes` | `-y` | Skip confirmation prompt |

### Empty Trash Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--yes` | `-y` | Skip confirmation prompt |

### Request Options (request, request-quick)

| Option | Alias | Description |
|--------|-------|-------------|
| `--title` | `-t` | Title for the request |
| `--message` | `-m` | Message/instructions for the recorder |
| `--custom-id` | | Custom identifier for tracking |
| `--expires` | `-e` | Expiration date (e.g., "12/31/2025 5:00pm") |
| `--collection` | `-c` | Collection ID to save recordings to |

### Request Edit Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--title` | `-t` | New title |
| `--message` | `-m` | New message |
| `--custom-id` | | New custom identifier |
| `--expires` | `-e` | New expiration date (or "never" to remove) |
| `--collection` | `-c` | New collection ID (empty to remove) |

### Request Delete Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--yes` | `-y` | Skip confirmation prompt |

### Request Details Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--verbose` | `-v` | Show download URLs for each item |

### Request Download Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--out` | `-o` | Output directory (default: .) |
| `--timeout` | `-t` | Delay between downloads in ms (default: 2000) |

### Requests List Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--verbose` | `-v` | Show full request links |

## Config File Location

Your configuration is stored at:

- **macOS/Linux**: `~/.config/cloudapp-dl/config.json`
- **Windows**: `%APPDATA%\cloudapp-dl\config.json`

## Session Management

The CLI automatically manages your session:

1. On login, your session ID and expiry are stored
2. Before each API request, the session validity is checked
3. If expired, the CLI automatically re-authenticates using stored credentials
4. Each API response updates the session cookie, keeping it fresh

## Quick Examples

```bash
# Login to your account
cloudapp-dl login

# List your files
cloudapp-dl list --per-page 24

# Export everything to CSV
cloudapp-dl export

# Download a single file by ID
cloudapp-dl get WnuPyJR5

# Download a single file by URL
cloudapp-dl download https://share.zight.com/ABC123

# Download from a list of URLs
cloudapp-dl download-list urls.txt --out ./videos

# Bulk download all videos from your account
cloudapp-dl bulk-download --videos-only --out ./my-videos

# Upload a file
cloudapp-dl upload ./screenshot.png

# Bulk upload a directory
cloudapp-dl bulk-upload ./screenshots/

# Create a video request link
cloudapp-dl request -t "Support" -m "Record your screen showing the issue"

# Create a quick video request
cloudapp-dl request-quick

# List all video requests
cloudapp-dl requests

# View request details and submitted items
cloudapp-dl request-details wgsX51

# Download all items from a request
cloudapp-dl request-download wgsX51 --out ./submissions

# Edit a request
cloudapp-dl request-edit ABC123 --title "New Title" --expires "12/31/2025"

# Delete a request
cloudapp-dl request-delete ABC123 --yes

# Delete a file (move to trash)
cloudapp-dl delete WnuPyJR5

# Permanently delete a file
cloudapp-dl delete WnuPyJR5 --permanent --yes

# View trash
cloudapp-dl trash

# Restore a file from trash
cloudapp-dl restore WnuPyJR5

# Empty trash
cloudapp-dl empty-trash --yes

# List your collections
cloudapp-dl collections
```

## Dependencies

- `axios` - HTTP client
- `cheerio` - HTML parsing
- `form-data` - Multipart form data for uploads
- `yargs` - CLI argument parsing

## Requirements

- Node.js >= 16.0.0

## Troubleshooting

### Session Expired
If you see session expired errors, simply run `cloudapp-dl login` again. The CLI will automatically re-authenticate using your stored credentials.

### Rate Limiting
If downloads/uploads are failing, try increasing the timeout between requests:
```bash
cloudapp-dl bulk-download --timeout 5000  # 5 second delay
cloudapp-dl bulk-upload ./files/ --timeout 5000
```

### File Already Exists
The bulk download and download-list commands automatically skip files that already exist in the output directory.

### Upload Failed
Make sure you're logged in and have permission to upload files to your Zight account. Check your account's storage limits.

## Contributing

Pull requests are welcome. For major changes, please open an issue first.

## License

[MIT](https://choosealicense.com/licenses/mit/)

---

Made with ❤️ by [ECOMGRADUATES LLC](https://ecomgraduates.com)