{"_id":"@clarion-app/dl-manager-frontend","name":"@clarion-app/dl-manager-frontend","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@clarion-app/dl-manager-frontend","version":"1.0.0","description":"Frontend for managing downloads in Clarion","main":"dist/index.js","scripts":{"build":"rm -rf dist && tsc"},"author":{"name":"Tim Schwartz","email":"tim@metaverse.systems"},"license":"MIT","dependencies":{"@clarion-app/types":"^1.0.3","@reduxjs/toolkit":"^1.9.5","react":"^18.2.0","react-dom":"^18.2.0","react-redux":"^8.0.5","react-router-dom":"^6.4.1","typescript":"^4.8.4"},"devDependencies":{"@types/react":"^18.0.21","@types/react-dom":"^18.0.6"},"customFields":{"clarion":{"api":["downloadManagerApi"],"routes":[{"path":"/clarion-app/download-manager/torrent-servers","element":"<TorrentServers />"},{"path":"/clarion-app/download-manager/torrents","element":"<Torrents />"}],"menu":{"name":"Download Manager","entries":[{"name":"Torrent Servers","path":"/clarion-app/download-manager/torrent-servers"},{"name":"Torrents","path":"/clarion-app/download-manager/torrents"}],"pinnedEntries":["Torrents"]}}},"types":"./dist/index.d.ts","gitHead":"cba0581a29d75be26ad7583739da557a2b0917cc","_id":"@clarion-app/dl-manager-frontend@1.0.0","_nodeVersion":"20.19.2","_npmVersion":"8.5.5","dist":{"integrity":"sha512-5sJS32lxsr44GN9JQJrbhxTndveNQrZkIw4X7wtREPw4xdakIpdTs8Ox42SCH6ET9rSmzTq5texzTFJq2xNugQ==","shasum":"fb6e1ce78022a966ea8dd9e12a497485a163b615","tarball":"https://registry.npmjs.org/@clarion-app/dl-manager-frontend/-/dl-manager-frontend-1.0.0.tgz","fileCount":35,"unpackedSize":125073,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCWP8lGEG6INotsUce5O2RXU5oRZoeSHFj8lFxYmbMaYAIhAK2Pv0CDK5G4GV9/ratMfk/4hDO+N8XKeSLQyt8a8qIS"}]},"_npmUser":{"name":"timschwartz","email":"tim@metaverse.systems","actor":{"name":"timschwartz","email":"tim@metaverse.systems","type":"user"}},"directories":{},"maintainers":[{"name":"timschwartz","email":"tim@metaverse.systems"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dl-manager-frontend_1.0.0_1750462259067_0.23513185989092755"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-20T23:30:58.956Z","1.0.0":"2025-06-20T23:30:59.264Z","modified":"2025-06-20T23:30:59.604Z"},"maintainers":[{"name":"timschwartz","email":"tim@metaverse.systems"}],"description":"Frontend for managing downloads in Clarion","author":{"name":"Tim Schwartz","email":"tim@metaverse.systems"},"license":"MIT","readme":"# Download Manager Frontend\n\nA React-based frontend component for managing downloads in Clarion. This package provides a comprehensive user interface for interacting with torrent servers and managing downloads.\n\n## Overview\n\nThe Download Manager Frontend is a Clarion app component that provides:\n- **Torrent Server Management**: Add, configure, and manage multiple torrent servers\n- **Torrent Download Management**: Create, monitor, and control torrent downloads\n- **Real-time Data Synchronization**: Powered by Redux Toolkit Query for efficient data fetching\n- **Responsive UI**: Built with Bulma CSS framework for modern, mobile-friendly interfaces\n- **Seamless Integration**: Designed to work within the Clarion app ecosystem\n\n## Features\n\n- **Server Management Interface**: Visual management of torrent servers with support for different client types\n- **Torrent Dashboard**: Comprehensive view of all torrents with filtering and search capabilities\n- **Real-time Status Updates**: Automatic refresh and status tracking of downloads\n- **Form Validation**: Client-side validation for all user inputs\n- **Error Handling**: Graceful error handling with user-friendly messages\n- **Multi-Client Support**: Interface adapts to different torrent client types\n- **Responsive Design**: Works seamlessly on desktop and mobile devices\n\n## Architecture\n\n### Core Components\n\n#### API Layer (`downloadManagerApi.ts`)\n- **Redux Toolkit Query**: Centralized API state management\n- **Automatic Caching**: Efficient data caching and invalidation\n- **Optimistic Updates**: Immediate UI feedback for user actions\n- **Error Handling**: Centralized error management across all endpoints\n\n#### React Components\n\n##### TorrentServers Component\n- **Server Listing**: Display all configured torrent servers\n- **Add Server Form**: Interface for adding new torrent servers\n- **Server Management**: Edit and delete existing servers\n- **Client Type Detection**: Automatic detection of supported client types\n\n##### Torrents Component\n- **Torrent Dashboard**: Overview of all active torrents\n- **Add Torrent Form**: Interface for adding new torrents via magnet URI\n- **Search & Filter**: Real-time filtering of torrents by name\n- **Status Display**: Visual indicators for download progress and completion\n\n##### Individual Item Components\n- **TorrentServer**: Individual server card with management actions\n- **Torrent**: Individual torrent card with status and controls\n\n### Type System (`types.ts`)\n\n#### TorrentServer Interface\n```typescript\ninterface TorrentServer {\n    local_node: string;    // Node identifier for distributed tracking\n    address: string;       // Server connection address (IP:Port)\n    type: string;         // Client type (e.g., \"Transmission\")\n    // Inherits LaravelModelType (id, created_at, updated_at, etc.)\n}\n```\n\n#### Torrent Interface\n```typescript\ninterface Torrent {\n    local_node: string;      // Node identifier\n    server_id: string;       // Reference to torrent server\n    user_id?: string;        // Associated user ID\n    magnetURI: string;       // Magnet link\n    hash_string?: string;    // Torrent hash identifier\n    completed_at?: string;   // Completion timestamp\n    name?: string;           // Display name\n    // Inherits LaravelModelType\n}\n```\n\n## API Integration\n\n### Available Hooks\n\n#### Torrent Server Hooks\n- `useGetTorrentServersQuery()` - Fetch all servers\n- `useGetTorrentServerQuery(id)` - Fetch specific server\n- `useCreateTorrentServerMutation()` - Create new server\n- `useUpdateTorrentServerMutation()` - Update existing server\n- `useDeleteTorrentServerMutation()` - Delete server\n- `useGetTorrentClientTypesQuery()` - Get supported client types\n\n#### Torrent Hooks\n- `useGetTorrentsQuery()` - Fetch all torrents\n- `useGetTorrentQuery(id)` - Fetch specific torrent\n- `useCreateTorrentMutation()` - Add new torrent\n- `useUpdateTorrentMutation()` - Update torrent\n- `useDeleteTorrentMutation()` - Remove torrent\n- `useMarkTorrentIncompleteMutation()` - Reset completion status\n\n### Authentication & Configuration\n\nThe frontend automatically handles:\n- **Bearer Token Authentication**: Automatically includes auth tokens in requests\n- **Backend URL Configuration**: Dynamic backend endpoint configuration\n- **User Context**: Maintains user information across components\n\n```typescript\n// Configuration is handled automatically by the Clarion framework\nexport const updateFrontend = (config: BackendType) => {\n    backend.url = config.url;\n    backend.token = config.token;\n    backend.user = config.user;\n};\n```\n\n## Usage Examples\n\n### Adding a Torrent Server\n1. Navigate to \"Torrent Servers\" in the Download Manager menu\n2. Click \"Add New Server\"\n3. Enter server address (e.g., `192.168.1.100:9091`)\n4. Select client type from dropdown\n5. Click \"Create Server\"\n\n### Adding a Torrent\n1. Navigate to \"Torrents\" in the Download Manager menu\n2. Click \"Add New Torrent\"\n3. Select a torrent server from the dropdown\n4. Paste the magnet URI\n5. Optionally specify a custom name\n6. Click \"Create Torrent\"\n\n### Monitoring Downloads\n- The Torrents page automatically refreshes to show current status\n- Completed torrents are visually distinguished\n- Use the search bar to filter torrents by name\n- Click individual torrents to view detailed information\n\n### Routes\n- `/clarion-app/download-manager/torrent-servers` - Server management interface\n- `/clarion-app/download-manager/torrents` - Torrent management interface\n\n### API Registration\nThe package exposes `downloadManagerApi` for use by other Clarion components:\n```typescript\nimport { downloadManagerApi } from '@clarion-app/download-manager-frontend';\n// Use API hooks in other components\n```\n\n## Dependencies\n\n### Core Dependencies\n- **React 18.2+**: Modern React with hooks and concurrent features\n- **Redux Toolkit Query**: State management and API caching\n- **React Router DOM**: Client-side routing\n- **TypeScript**: Type safety and enhanced development experience\n\n### Clarion Dependencies\n- **@clarion-app/types**: Shared type definitions for the Clarion ecosystem\n\n### UI Framework\n- **Bulma CSS**: Modern CSS framework (classes used in components)\n- **Font Awesome**: Icons (referenced in components)\n\n## Development\n\n### Building the Package\n```bash\nnpm run build\n```\n\nThis compiles TypeScript to JavaScript in the `dist/` directory.\n\n### Type Checking\nThe package uses strict TypeScript configuration:\n- Strict mode enabled\n- Full type checking for all React components\n- Integration with Clarion type system\n\n## Component API\n\n### TorrentServers Component\n```typescript\n// No props required - fully self-contained\n<TorrentServers />\n```\n\n### Torrents Component  \n```typescript\n// No props required - fully self-contained\n<Torrents />\n```\n\n### Individual Components\n```typescript\n// TorrentServer component\n<TorrentServer \n  server={serverData} \n  onDeleted={handleDeleted}\n/>\n\n// Torrent component\n<Torrent \n  torrent={torrentData}\n  onDeleted={handleDeleted} \n/>\n```\n\n## Error Handling\n\nThe frontend provides comprehensive error handling:\n- **Network Errors**: Graceful handling of connection issues\n- **Validation Errors**: Client-side form validation\n- **Server Errors**: User-friendly error messages\n- **Loading States**: Visual feedback during operations\n\n## Responsive Design\n\nAll components are built with mobile-first responsive design:\n- **Mobile Optimized**: Touch-friendly interfaces\n- **Tablet Support**: Optimized layouts for medium screens  \n- **Desktop Enhanced**: Full-featured desktop experience\n- **Accessibility**: Proper semantic HTML and ARIA labels\n\n## Integration with Backend\n\nThe frontend seamlessly integrates with the Download Manager Backend:\n- **Automatic Data Sync**: Real-time updates via Redux Toolkit Query\n- **Optimistic Updates**: Immediate UI feedback\n- **Error Recovery**: Automatic retry and error handling\n- **Caching Strategy**: Efficient data caching to minimize API calls\n","readmeFilename":"README.md","_rev":"1-7b97002bfe10e22780114af7bdab0509"}