quickbooks_types/models/
attachable.rs

1use std::path::{Path, PathBuf};
2
3use serde::{Deserialize, Serialize};
4use serde_with::skip_serializing_none;
5
6use super::common::{CustomField, MetaData, NtRef};
7use crate::{QBCreatable, QBDeletable, QBFullUpdatable, QBItem, QBToRef, QBTypeError};
8
9#[skip_serializing_none]
10#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, Default)]
11#[serde(rename_all = "PascalCase", default)]
12#[cfg_attr(
13    feature = "builder",
14    derive(Builder),
15    builder(default, build_fn(error = "QBTypeError"), setter(into, strip_option))
16)]
17
18/// Attachable
19///
20/// Represents a file attachment or note that can be linked to other `QuickBooks` entities (for example: Invoice, Bill, Customer).
21///
22/// Notes:
23/// - With the "builder" feature enabled, `Attachable::new().file(path)` sets `file_path` for upload and derives `file_name` and `content_type` from the path.
24/// - This crate models metadata only; HTTP upload logic and file bytes handling should be implemented in your client.
25///
26/// API reference:
27/// <https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/attachable>
28pub struct Attachable {
29    /// The unique ID of the entity
30    pub id: Option<String>,
31    /// The unique sync token of the entity, used for concurrency control
32    pub sync_token: Option<String>,
33    /// Metadata about the entity
34    #[serde(skip_serializing)]
35    pub meta_data: Option<MetaData>,
36    /// File name of the attachment
37    #[cfg_attr(feature = "builder", builder(setter(custom)))]
38    pub file_name: Option<String>,
39    /// Filesystem path used during upload (builder feature only); not serialized.
40    #[cfg_attr(feature = "builder", builder(setter(custom)))]
41    #[serde(skip)]
42    pub file_path: Option<PathBuf>,
43    /// Private note for the attachment
44    pub note: Option<String>,
45    /// Category of the attachment
46    pub category: Option<AttachmentCategory>,
47    /// Content type of the attachment
48    #[cfg_attr(feature = "builder", builder(setter(custom)))]
49    pub content_type: Option<String>,
50    pub place_name: Option<String>,
51    /// References to the transaction object to which this attachable file is to be linked
52    #[cfg_attr(feature = "builder", builder(setter(strip_option)))]
53    pub attachable_ref: Option<Vec<AttachableRef>>,
54    /// Longitude of the place where the attachment was taken
55    pub long: Option<String>,
56    /// Tag for the attachment
57    pub tag: Option<String>,
58    /// Latitude of the place where the attachment was taken
59    pub lat: Option<String>,
60    /// URI for accessing the file
61    pub file_access_uri: Option<String>,
62    /// Size of the file in bytes
63    pub size: Option<f64>,
64    /// URI for accessing the thumbnail of the file
65    pub thumbnail_file_access_uri: Option<String>,
66    /// Temporary download URI for the file
67    pub temp_download_uri: Option<String>,
68}
69
70/// Derives the content type from a file extension
71#[must_use]
72pub fn content_type_from_ext(ext: &str) -> Option<&'static str> {
73    let out = match ext {
74        "ai" | "eps" => "application/postscript",
75        "csv" => "text/csv",
76        "doc" => "application/msword",
77        "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
78        "gif" => "image/gif",
79        "jpeg" => "image/jpeg",
80        "jpg" => "image/jpg",
81        "png" => "image/png",
82        "rtf" => "text/rtf",
83        "txt" => "text/plain",
84        "tif" => "image/tiff",
85        "ods" => "application/vnd.oasis.opendocument.spreadsheet",
86        "pdf" => "application/pdf",
87        "xls" => "application/vnd.ms-excel",
88        "xml" => "text/xml",
89        "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
90        _ => return None,
91    };
92    Some(out)
93}
94
95#[cfg(feature = "builder")]
96impl AttachableBuilder {
97    /// Sets `file_path` (for upload), and derives `file_name` and `content_type` from it.
98    /// On success, stores the original path for upload, sets `file_name` to the basename, and infers `content_type` from the file extension.
99    pub fn file(&mut self, path: &impl AsRef<Path>) -> Result<&mut Self, QBTypeError> {
100        let path = path.as_ref();
101
102        self.file_path = Some(Some(path.to_path_buf()));
103
104        self.file_name = Some(Some(
105            path.file_name()
106                .ok_or(QBTypeError::ValidationError(
107                    "No file name on file path".into(),
108                ))?
109                .to_str()
110                .ok_or(QBTypeError::ValidationError(
111                    "Could not turn file name into string".into(),
112                ))?
113                .to_owned(),
114        ));
115
116        self.content_type = Some(
117            content_type_from_ext(
118                path.extension()
119                    .ok_or(QBTypeError::ValidationError(
120                        "No extension on file/dir".into(),
121                    ))?
122                    .to_string_lossy()
123                    .as_ref(),
124            )
125            .map(|f| f.to_owned()),
126        );
127
128        Ok(self)
129    }
130}
131
132/// Trait for all entities that can be attached as files/notes.
133///
134/// Preconditions for upload:
135/// - `file_name` or `note` must be present;
136/// - `file_path` must be present.
137/// - `content_type` must be present.
138/// - `can_upload()` returns an error if required fields are missing.
139pub trait QBAttachable {
140    /// Returns Ok(()) when the instance has the fields required for upload.
141    fn can_upload(&self) -> Result<(), QBTypeError>;
142    fn file_path(&self) -> Option<&Path>;
143}
144impl QBAttachable for Attachable {
145    fn can_upload(&self) -> Result<(), QBTypeError> {
146        if self.note.is_none() && self.file_name.is_none() {
147            return Err(QBTypeError::MissingField("note"));
148        }
149        if self.file_name.is_none() {
150            return Err(QBTypeError::MissingField("file_name"));
151        }
152        Ok(())
153    }
154
155    fn file_path(&self) -> Option<&Path> {
156        self.file_path.as_deref()
157    }
158}
159
160/// `AttachmentCategory`
161///
162/// Enumerates the category of an attachment (for example: Document, Image, Receipt).
163#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, Default)]
164pub enum AttachmentCategory {
165    ContactPhoto,
166    Document,
167    Image,
168    Receipt,
169    Signature,
170    Sound,
171    #[default]
172    Other,
173}
174
175/// AttachableRef
176///
177/// A reference that links an attachment to a target `QuickBooks` entity (such as an Invoice line or a Bill).
178///
179/// Most callers will construct this via `QBToAttachableRef::to_attach_ref()` on an entity that implements `QBToRef`.
180#[skip_serializing_none]
181#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, Default)]
182#[serde(rename_all = "PascalCase", default)]
183#[cfg_attr(feature = "builder", derive(Builder), builder(default))]
184pub struct AttachableRef {
185    /// Indicates if the entity should be included on send
186    pub include_on_send: Option<bool>,
187    /// Line information for the entity
188    pub line_info: Option<String>,
189    /// Indicates if the entity is a reference only
190    pub no_ref_only: Option<bool>,
191    /// Custom fields for the entity
192    pub custom_field: Option<Vec<CustomField>>,
193    /// Type of the entity
194    #[serde(rename = "type")]
195    pub ref_type: Option<String>,
196    /// Indicates if the entity is inactive
197    pub inactive: Option<bool>,
198    /// The unique ID of the entity
199    pub entity_ref: Option<NtRef>,
200}
201
202impl From<NtRef> for AttachableRef {
203    fn from(value: NtRef) -> Self {
204        AttachableRef {
205            entity_ref: Some(value),
206            ..Default::default()
207        }
208    }
209}
210
211/// Trait for entities that can be converted to a reference for an attachment.
212pub trait QBToAttachableRef: QBToRef {
213    fn to_attach_ref(&self) -> Result<AttachableRef, QBTypeError> {
214        let value = self.to_ref()?;
215        Ok(value.into())
216    }
217}
218
219impl<T: QBToRef> QBToAttachableRef for T {}
220
221impl QBCreatable for Attachable {
222    fn can_create(&self) -> bool {
223        (self.file_name.is_some() || self.note.is_some())
224            && self.content_type.is_some()
225            && self.file_path.is_some()
226    }
227}
228impl QBDeletable for Attachable {}
229impl QBFullUpdatable for Attachable {
230    fn can_full_update(&self) -> bool {
231        self.has_read() && self.can_create()
232    }
233}
quickbooks_types/models/attachable.rs

quickbooks_types/models/
attachable.rs
