files_sdk/
lib.rs

1//! Files.com Rust SDK
2//!
3//! A comprehensive Rust client for the [Files.com](https://files.com) REST API, providing full access to
4//! file operations, user management, sharing, automation, and administrative features.
5//!
6//! ## Features
7//!
8//! - **File Operations**: Upload, download, copy, move, delete files and folders
9//! - **User & Access Management**: Users, groups, permissions, API keys, sessions
10//! - **Sharing**: Bundles (share links), file requests, inbox uploads
11//! - **Automation**: Webhooks, behaviors, remote servers, automations
12//! - **Administration**: Site settings, history, notifications, billing
13//!
14//! ## Quick Start
15//!
16//! ```rust,no_run
17//! use files_sdk::{FilesClient, files::FileHandler};
18//!
19//! #[tokio::main]
20//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
21//!     // Create client with API key
22//!     let client = FilesClient::builder()
23//!         .api_key("your-api-key")
24//!         .build()?;
25//!
26//!     // Use handlers for typed operations
27//!     let file_handler = FileHandler::new(client.clone());
28//!
29//!     // Upload a file
30//!     let data = b"Hello, Files.com!";
31//!     file_handler.upload_file("/path/to/file.txt", data).await?;
32//!
33//!     Ok(())
34//! }
35//! ```
36//!
37//! ## Core Usage Patterns
38//!
39//! ### Client Creation
40//!
41//! The client uses a builder pattern for flexible configuration:
42//!
43//! ```rust,no_run
44//! use files_sdk::FilesClient;
45//!
46//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
47//! // Basic client with default settings
48//! let client = FilesClient::builder()
49//!     .api_key("your-api-key")
50//!     .build()?;
51//!
52//! // Custom configuration
53//! let client = FilesClient::builder()
54//!     .api_key("your-api-key")
55//!     .base_url("https://app.files.com/api/rest/v1".to_string())
56//!     .timeout(std::time::Duration::from_secs(60))
57//!     .build()?;
58//! # Ok(())
59//! # }
60//! ```
61//!
62//! ### File Upload (Two-Stage Process)
63//!
64//! Files.com uses a two-stage upload process:
65//!
66//! ```rust,no_run
67//! use files_sdk::{FilesClient, files::{FileActionHandler, FileHandler}};
68//!
69//! # #[tokio::main]
70//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
71//! let client = FilesClient::builder()
72//!     .api_key("your-api-key")
73//!     .build()?;
74//!
75//! // Stage 1: Begin upload to get upload URLs
76//! let file_action = FileActionHandler::new(client.clone());
77//! let upload_info = file_action
78//!     .begin_upload("/uploads/myfile.txt", Some(1024), true)
79//!     .await?;
80//!
81//! // Stage 2: Upload file data (simplified - see FileHandler for complete implementation)
82//! let file_handler = FileHandler::new(client.clone());
83//! let data = b"file contents";
84//! file_handler.upload_file("/uploads/myfile.txt", data).await?;
85//! # Ok(())
86//! # }
87//! ```
88//!
89//! ## Error Handling
90//!
91//! The SDK provides comprehensive error handling:
92//!
93//! ```rust,no_run
94//! use files_sdk::{FilesClient, FilesError, files::FileHandler};
95//!
96//! # #[tokio::main]
97//! # async fn main() {
98//! let client = FilesClient::builder()
99//!     .api_key("test-key")
100//!     .build()
101//!     .unwrap();
102//!
103//! let handler = FileHandler::new(client);
104//!
105//! match handler.download_file("/path/to/file.txt").await {
106//!     Ok(file) => println!("Downloaded: {:?}", file),
107//!     Err(FilesError::NotFound { message }) => {
108//!         println!("File not found: {}", message);
109//!     }
110//!     Err(FilesError::AuthenticationFailed { message }) => {
111//!         println!("Invalid API key: {}", message);
112//!     }
113//!     Err(e) => println!("Other error: {}", e),
114//! }
115//! # }
116//! ```
117//!
118//! ## Authentication
119//!
120//! Files.com uses API key authentication via the `X-FilesAPI-Key` header.
121//! API keys can be obtained from the Files.com web interface under Account Settings.
122
123// Core modules
124pub mod client;
125pub mod types;
126
127// Domain modules
128pub mod admin;
129pub mod advanced;
130pub mod as2;
131pub mod automation;
132pub mod files;
133pub mod logs;
134pub mod messages;
135pub mod security;
136pub mod sharing;
137pub mod storage;
138pub mod users;
139
140// Misc (to be moved or removed)
141pub mod webhook_tests;
142
143// Re-export client types
144pub use client::{FilesClient, FilesClientBuilder};
145
146// Re-export common types
147pub use types::{FileEntity, FileUploadPartEntity, FolderEntity, PaginationInfo};
148
149// Re-export all handlers for backward compatibility
150pub use admin::{
151    ActionNotificationExportHandler, ActionNotificationExportResultHandler, HistoryExportHandler2,
152    HistoryExportResultHandler2, HistoryHandler, InvoiceHandler, PaymentHandler, SiteHandler,
153};
154pub use advanced::{
155    AppHandler, ChildSiteManagementPolicyHandler, DnsRecordHandler, EmailIncomingMessageHandler,
156    ExternalEventHandler, FormFieldSetHandler, HolidayRegionHandler, ShareGroupHandler,
157    SiemHttpDestinationHandler, StyleHandler,
158};
159pub use as2::{
160    As2IncomingMessageHandler, As2OutgoingMessageHandler, As2PartnerHandler, As2StationHandler,
161};
162pub use automation::{
163    AutomationHandler, AutomationRunHandler, BehaviorHandler, RemoteMountBackendHandler,
164    RemoteServerHandler, SyncHandler, SyncRunHandler,
165};
166pub use files::{
167    FileActionHandler, FileCommentHandler, FileCommentReactionHandler, FileHandler,
168    FileMigrationHandler, FileMigrationLogHandler, FolderHandler,
169};
170pub use logs::{
171    ApiRequestLogHandler, AutomationLogHandler, EmailLogHandler, ExavaultApiRequestLogHandler,
172    FtpActionLogHandler, OutboundConnectionLogHandler, PublicHostingRequestLogHandler,
173    SettingsChangeHandler, SftpActionLogHandler, SyncLogHandler, WebDavActionLogHandler,
174};
175pub use messages::{
176    MessageCommentHandler, MessageCommentReactionHandler, MessageHandler, MessageReactionHandler,
177    NotificationHandler,
178};
179pub use security::{ClickwrapHandler, GpgKeyHandler, IpAddressHandler, SftpHostKeyHandler};
180pub use sharing::{
181    BundleActionHandler, BundleDownloadHandler, BundleHandler, BundleNotificationHandler,
182    BundleRecipientHandler, BundleRegistrationHandler, InboxRecipientHandler,
183    InboxRegistrationHandler2, InboxUploadHandler, RequestHandler,
184};
185pub use storage::{
186    BandwidthSnapshotHandler, LockHandler, PriorityHandler, ProjectHandler,
187    RemoteBandwidthSnapshotHandler, RestoreHandler, SnapshotHandler, UsageDailySnapshotHandler,
188    UsageSnapshotHandler,
189};
190pub use users::{
191    ApiKeyCurrentHandler, ApiKeyHandler, CurrentUserHandler, GroupHandler, GroupUserHandler,
192    PermissionHandler, PublicKeyHandler, SessionHandler, SsoStrategyHandler, UserCipherUseHandler,
193    UserHandler, UserLifecycleRuleHandler, UserRequestHandler, UserSftpClientUseHandler,
194};
195
196// Error handling
197use thiserror::Error;
198
199/// Errors that can occur when using the Files.com API
200#[derive(Error, Debug)]
201pub enum FilesError {
202    /// HTTP request failed
203    #[error("HTTP request failed: {0}")]
204    Request(#[from] reqwest::Error),
205
206    /// Bad Request (400)
207    #[error("Bad Request (400): {message}")]
208    BadRequest { message: String },
209
210    /// Authentication failed (401)
211    #[error("Authentication failed (401): {message}")]
212    AuthenticationFailed { message: String },
213
214    /// Forbidden (403)
215    #[error("Forbidden (403): {message}")]
216    Forbidden { message: String },
217
218    /// Not Found (404)
219    #[error("Not Found (404): {message}")]
220    NotFound { message: String },
221
222    /// Conflict (409) - Resource already exists or state conflict
223    #[error("Conflict (409): {message}")]
224    Conflict { message: String },
225
226    /// Precondition Failed (412) - Conditional request failed
227    #[error("Precondition Failed (412): {message}")]
228    PreconditionFailed { message: String },
229
230    /// Unprocessable Entity (422) - Validation error
231    #[error("Unprocessable Entity (422): {message}")]
232    UnprocessableEntity { message: String },
233
234    /// Locked (423) - Resource is locked
235    #[error("Locked (423): {message}")]
236    Locked { message: String },
237
238    /// Rate Limited (429)
239    #[error("Rate Limited (429): {message}")]
240    RateLimited { message: String },
241
242    /// Internal Server Error (500)
243    #[error("Internal Server Error (500): {message}")]
244    InternalServerError { message: String },
245
246    /// Service Unavailable (503)
247    #[error("Service Unavailable (503): {message}")]
248    ServiceUnavailable { message: String },
249
250    /// Generic API error with status code
251    #[error("API error ({code}): {message}")]
252    ApiError { code: u16, message: String },
253
254    /// Configuration error
255    #[error("Configuration error: {0}")]
256    ConfigError(String),
257
258    /// JSON serialization/deserialization error
259    #[error("JSON error: {0}")]
260    JsonError(#[from] serde_json::Error),
261}
262
263/// Result type for Files.com operations
264pub type Result<T> = std::result::Result<T, FilesError>;
files_sdk/lib.rs

files_sdk/
lib.rs
