update docs

README.md

@@ -1,11 +1,16 @@
 # Ferrtable: Ferris the Crab's Favorite Airtable Client
 
-A power vacuum churns where the venerable
-[airtable-api](https://crates.io/crates/airtable-api) (archived but not
-forgotten) once stood tall. The world calls for a new leader to carry the
-fallen torch. From the dust rises Ferrtable: to abase SQL supremacy, to turn
-all the tables, to rise inexorably to the top of the field, and to set the
-record straight.
+Ferrtable provides async Rust bindings for a subset of the
+[Airtable web API](https://airtable.com/developers/web/api/introduction).
+Notably, it allows records to be read from and written to arbitrary Rust types
+that implement the `Clone`, `serde::Deserialize`, and `serde::Serialize` traits.
+
+This crate follows in the footsteps of the
+[airtable-api](https://crates.io/crates/airtable-api) crate from Oxide Computer
+Company, which appears to have be archived and unmaintained since 2022.
+By comparison, Ferrtable aims to provide a more flexible and expressive client
+interface as well as greater control over paginated responses with the help of
+async [streams](https://doc.rust-lang.org/book/ch17-04-streams.html).
 
 ## Status: Work in Progress
 
@@ -23,64 +28,64 @@ use futures::prelude::*;
 // Deserialize, and Serialize.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 struct MyRecord {
-  #[serde(rename = "Name")]
-  name: String,
+    #[serde(rename = "Name")]
+    name: String,
 
-  #[serde(rename = "Notes")]
-  notes: String,
+    #[serde(rename = "Notes")]
+    notes: String,
 
-  #[serde(rename = "Assignee")]
-  assignee: Option<String>,
+    #[serde(rename = "Assignee")]
+    assignee: Option<String>,
 
-  #[serde(rename = "Status")]
-  status: Status,
+    #[serde(rename = "Status")]
+    status: Status,
 
-  #[serde(rename = "Attachments")]
-  attachments: Vec<ferrtable::cell_values::AttachmentRead>,
+    #[serde(rename = "Attachments")]
+    attachments: Vec<ferrtable::cell_values::AttachmentRead>,
 }
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
 enum Status {
-  Todo,
+    Todo,
 
-  #[serde(rename = "In progress")]
-  InProgress,
+    #[serde(rename = "In progress")]
+    InProgress,
 
-  Done,
+    Done,
 }
 
 #[tokio::main]
 async fn main() {
-  let client = ferrtable::Client::new_from_access_token("******").unwrap();
+    let client = ferrtable::Client::new_from_access_token("******").unwrap();
 
-  client
-    .create_records([MyRecord {
-      name: "Steal Improbability Drive".to_owned(),
-      notes: "Just for fun, no other reason.".to_owned(),
-      assignee: None,
-      status: Status::InProgress,
-      attachments: vec![],
-    }])
-    .with_base_id("***".to_owned())
-    .with_table_id("***".to_owned())
-    .build()
-    .unwrap()
-    .execute()
-    .await
-    .unwrap();
+    client
+        .create_records([MyRecord {
+            name: "Steal Improbability Drive".to_owned(),
+            notes: "Just for fun, no other reason.".to_owned(),
+            assignee: None,
+            status: Status::InProgress,
+            attachments: vec![],
+        }])
+        .with_base_id("***".to_owned())
+        .with_table_id("***".to_owned())
+        .build()
+        .unwrap()
+        .execute()
+        .await
+        .unwrap();
 
-  let mut rec_stream = client
-    .list_records()
-    .with_base_id("***".to_owned())
-    .with_table_id("***".to_owned())
-    .with_filter("{status} = 'Todo' || {status} = 'In Progress'".to_owned())
-    .build()
-    .unwrap()
-    .stream_items::<MyRecord>();
+    let mut rec_stream = client
+        .list_records()
+        .with_base_id("***".to_owned())
+        .with_table_id("***".to_owned())
+        .with_filter("{status} = 'Todo' || {status} = 'In Progress'".to_owned())
+        .build()
+        .unwrap()
+        .stream_items::<MyRecord>();
 
-  while let Some(result) = rec_stream.next().await {
-    let rec = result.unwrap();
-    dbg!(rec.fields);
-  }
+    while let Some(result) = rec_stream.next().await {
+        let rec = result.unwrap();
+        dbg!(rec.fields);
+    }
 }
 ```

ferrtable/Cargo.toml

@@ -4,7 +4,6 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
-chrono = { version = "0.4.42", features = ["serde"] }
 derive_builder = { version = "0.20.2", features = ["clippy"] }
 futures = "0.3.31"
 percent-encoding = "2.3.2"
@@ -12,3 +11,7 @@ reqwest = { version = "0.12.23", features = ["json"] }
 serde = { version = "1.0.219", features = ["derive"] }
 serde_json = "1.0.143"
 thiserror = "2.0.16"
+chrono = { version = "0.4.42", features = ["serde"], optional = true }
+
+[features]
+chrono = ["dep:chrono"]

ferrtable/src/cell_values.rs

@@ -12,12 +12,12 @@ use serde::{Deserialize, Serialize};
 /// Read only.
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub struct AiTextValue {
-    state: String,
+    pub state: String,
     #[serde(rename = "isStale")]
-    is_stale: bool,
+    pub is_stale: bool,
     #[serde(rename = "errorType")]
-    error_type: Option<String>,
-    value: Option<String>,
+    pub error_type: Option<String>,
+    pub value: Option<String>,
 }
 
 /// Attachments allow you to add images, documents, or other files which can
@@ -33,27 +33,27 @@ pub struct AiTextValue {
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub struct AttachmentRead {
     /// Unique attachment id
-    id: String,
+    pub id: String,
     /// Content type, e.g. "image/jpeg"
     #[serde(rename = "type")]
-    type_: String,
+    pub type_: String,
     /// Filename, e.g. "foo.jpg"
-    filename: String,
+    pub filename: String,
     /// Height, in pixels (these may be available if the attachment is an
     /// image)
-    height: Option<i32>,
+    pub height: Option<i32>,
     /// File size, in bytes
-    size: usize,
-    /// url, e.g. "https://v5.airtableusercontent.com/foo".
+    pub size: usize,
+    /// url, e.g. `"https://v5.airtableusercontent.com/foo"`.
     ///
     /// URLs returned will expire 2 hours after being returned from our API.
     /// If you want to persist the attachments, we recommend downloading
     /// them instead of saving the URL. See our support article for more
     /// information.
-    url: String,
+    pub url: String,
     /// Width, in pixels (these may be available if the attachment is an
     /// image)
-    width: Option<i32>,
+    pub width: Option<i32>,
     // TODO: Add `thumbnails` field.
 }
 
@@ -115,9 +115,9 @@ pub struct Barcode {
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub struct Button {
     /// Button label
-    label: String,
+    pub label: String,
     /// For "Open URL" actions, the computed url value
-    url: Option<String>,
+    pub url: Option<String>,
 }
 
 /// A collaborator field lets you add collaborators to your records.
@@ -129,23 +129,23 @@ pub struct Button {
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub struct CollaboratorRead {
     /// User id or group id
-    id: String,
+    pub id: String,
     /// User's email address
-    email: Option<String>,
+    pub email: Option<String>,
     /// User's display name (may be omitted if the user hasn't created an
     /// account)
-    name: Option<String>,
+    pub name: Option<String>,
     /// User's collaborator permission Level
     ///
     /// This is only included if you're observing a webhooks response.
     #[serde(rename = "permissionLevel")]
-    permission_level: Option<String>,
+    pub permission_level: Option<String>,
     /// User's profile picture
     ///
     /// This is only included if it exists for the user and you're observing
     /// a webhooks response.
     #[serde(rename = "profilePicUrl")]
-    profile_pic_url: Option<String>,
+    pub profile_pic_url: Option<String>,
 }
 
 /// Write only. Use CollaboratorRead for reading from fields.
@@ -161,7 +161,8 @@ pub enum CollaboratorWrite {
     },
 }
 
-/// Option<FormulaResult> should cover all values generated by a formula field.
+/// `Option<FormulaResult>` should cover all values generated by a formula
+/// field.
 ///
 /// Read only.
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]

ferrtable/src/lib.rs

@@ -1,3 +1,88 @@
+//! # Ferrtable: Ferris the Crab's Favorite Airtable Client
+//!
+//! ## Status: Work in Progress
+//!
+//! Only a limited set of operations are currently supported. Any version bumps
+//! before version 0.1 may include breaking changes to the crate API.
+//!
+//! ## Usage
+//!
+//! ```ignore
+//! use futures::prelude::*;
+//!
+//! // Ferrtable allows us to use any record types that implement Clone,
+//! // Deserialize, and Serialize.
+//! #[derive(Clone, Debug, Deserialize, Serialize)]
+//! struct MyRecord {
+//!     #[serde(rename = "Name")]
+//!     name: String,
+//!
+//!     #[serde(rename = "Notes")]
+//!     notes: String,
+//!
+//!     #[serde(rename = "Assignee")]
+//!     assignee: Option<String>,
+//!
+//!     #[serde(rename = "Status")]
+//!     status: Status,
+//!
+//!     #[serde(rename = "Attachments")]
+//!     attachments: Vec<ferrtable::cell_values::AttachmentRead>,
+//! }
+//!
+//! #[derive(Clone, Debug, Deserialize, Serialize)]
+//! enum Status {
+//!     Todo,
+//!
+//!     #[serde(rename = "In progress")]
+//!     InProgress,
+//!
+//!     Done,
+//! }
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let client = ferrtable::Client::new_from_access_token("******").unwrap();
+//!
+//!     client
+//!         .create_records([MyRecord {
+//!             name: "Steal Improbability Drive".to_owned(),
+//!             notes: "Just for fun, no other reason.".to_owned(),
+//!             assignee: None,
+//!             status: Status::InProgress,
+//!             attachments: vec![],
+//!         }])
+//!         .with_base_id("***".to_owned())
+//!         .with_table_id("***".to_owned())
+//!         .build()
+//!         .unwrap()
+//!         .execute()
+//!         .await
+//!         .unwrap();
+//!
+//!     let mut rec_stream = client
+//!         .list_records()
+//!         .with_base_id("***".to_owned())
+//!         .with_table_id("***".to_owned())
+//!         .with_filter("{status} = 'Todo' || {status} = 'In Progress'".to_owned())
+//!         .build()
+//!         .unwrap()
+//!         .stream_items::<MyRecord>();
+//!
+//!     while let Some(result) = rec_stream.next().await {
+//!         let rec = result.unwrap();
+//!         dbg!(rec.fields);
+//!     }
+//! }
+//! ```
+//!
+//! ## Features
+//!
+//! ### `chrono`
+//!
+//! Deserializes certain Airtable timestamp fields as `chrono::DateTime` values
+//! instead of [`String`]s. Disabled by default.
+
 pub mod cell_values;
 pub mod client;
 pub mod errors;

ferrtable/src/list_bases.rs

@@ -56,7 +56,7 @@ pub struct Base {
 }
 
 #[derive(Clone, Deserialize)]
-pub struct ListBasesResponse {
+struct ListBasesResponse {
     /// If there are more records, the response will contain an offset. Pass
     /// this offset into the next request to fetch the next page of records.
     offset: Option<String>,

ferrtable/src/list_records.rs

@@ -84,7 +84,7 @@ impl ListRecordsQuery {
 }
 
 #[derive(Clone, Deserialize)]
-pub struct ListRecordsResponse<T>
+struct ListRecordsResponse<T>
 where
     T: Clone,
 {

ferrtable/src/types.rs

@@ -1,3 +1,4 @@
+#[cfg(feature = "chrono")]
 use chrono::{DateTime, Utc};
 use serde::Deserialize;
 
@@ -10,9 +11,15 @@ where
     pub id: String,
 
     /// Timestamp of record creation.
+    #[cfg(feature = "chrono")]
     #[serde(rename = "createdTime")]
     pub created_time: DateTime<Utc>,
 
+    /// Timestamp of record creation.
+    #[cfg(not(feature = "chrono"))]
+    #[serde(rename = "createdTime")]
+    pub created_time: String,
+
     /// Contents of record data.
     pub fields: T,