Crate jmap_contacts_types

Expand description

RFC 9610 + RFC 9553 data types for JMAP Contacts.

Provides AddressBook, AddressBookRights, ContactCard, ContactCardFilterCondition, ContactCardComparator, ContactsCapability, and ContactsAccountCapability.

This crate is types-only: no method handlers, no async, no network I/O. It sits between jmap-types (shared JMAP base primitives) and the server/client crates that consume these types.

All types implement serde::Serialize and serde::Deserialize with the camelCase field names required by the JMAP wire format.

§JSContact sub-object types

The RFC 9553 JSContact sub-object types (Name, EmailAddress, Phone, Address, etc.) live in the dedicated jmap-jscontact-types crate and are re-exported here for caller ergonomics. The ContactCard struct keeps its 22 sub-object fields typed as Option<serde_json::Value> as the wire-format anchor — typed access is opt-in via serde_json::from_value on a chosen field.

use jmap_contacts_types::{ContactCard, Name};

let card_json = serde_json::json!({
    "name": {
        "components": [
            { "kind": "given", "value": "Vincent" },
            { "kind": "surname", "value": "van Gogh" }
        ],
        "isOrdered": true
    }
});
let card: ContactCard = serde_json::from_value(card_json).unwrap();
let name: Name = serde_json::from_value(card.name.unwrap()).unwrap();
assert_eq!(name.components.unwrap()[0].value, "Vincent");

§Logging safety

This crate derives plain Debug on all PII-bearing types (ContactCard, AddressBook, and the 30+ re-exported RFC 9553 JSContact sub-types: Name, EmailAddress, Phone, Address, Note, Anniversary, PersonalInfo, CryptoKey, etc.). Consumers using tracing or log macros that interpolate values via ? (debug) or % (display) emit the full record contents to the configured sink. This includes phone numbers, email addresses, postal addresses, names, notes, and CryptoKey URIs — all of which are typically regulated as personally-identifying information under GDPR Article 5, CCPA §1798.100, and similar privacy frameworks.

Consumers SHOULD wrap PII-bearing values in a redacting newtype before logging, or use a structured-logging field-allowlist:

// BAD — leaks every name, phone, email, address into the log sink.
tracing::debug!(card = ?contact_card, "fetched contact");

// GOOD — emits only the opaque id and surfaces nothing else.
tracing::debug!(card_id = %contact_card.id.as_deref().unwrap_or_default(), "fetched contact");

The workspace has a Debug-redaction precedent in jmap-base-client for credential-bearing types (BearerAuth, BasicAuth, Session, AccountInfo) but not for PII-bearing types. The decision whether to propagate that precedent workspace-wide is tracked by a separate workspace-policy bead; this crate’s current posture is plain Debug plus this safety contract. JMAP-glx8.26.

§Example

use jmap_contacts_types::AddressBook;

let json = r#"{
    "id": "ab1",
    "name": "Personal",
    "sortOrder": 0,
    "isDefault": true,
    "isSubscribed": true,
    "shareWith": null,
    "myRights": {
        "mayRead": true,
        "mayWrite": true,
        "mayShare": true,
        "mayDelete": false
    }
}"#;

let ab: AddressBook = serde_json::from_str(json).unwrap();
assert_eq!(ab.name, "Personal");

Re-exports§

pub use addressbook::AddressBook;
pub use addressbook::AddressBookRights;
pub use backend::AddressBookProperty;
pub use backend::ContactCardProperty;
pub use capability::ContactsAccountCapability;
pub use capability::ContactsCapability;
pub use capability::JMAP_CONTACTS_URI;
pub use card::ContactCard;
pub use card::ContactCardComparator;
pub use card::ContactCardFilter;
pub use card::ContactCardFilterCondition;
pub use collision::CollisionError;
pub use card::prop as comparator_prop;
pub use jmap_jscontact_types as jscontact;

Modules§

addressbook: RFC 9610 §2 — AddressBook object and component types.
backend: Property selector enums and jmap_types::JmapObject impls for JMAP Contacts types.
capability: RFC 9610 §1.4 — JMAP Contacts capability objects.
card: RFC 9610 §3 — ContactCard object and filter types.
collision: Runtime detection of vendor-extras key collisions with typed fields.

Structs§

Address: A postal or geographic address (RFC 9553 §2.5.1).
AddressComponent: A single component of an Address (RFC 9553 §2.5.1.2).
Anniversary: A memorable date or event (RFC 9553 §2.8.1).
Author: The author of a Note (RFC 9553 §2.8.3).
Calendar: A calendaring resource (RFC 9553 §2.4.1).
CryptoKey: A cryptographic key or certificate associated with a Card (RFC 9553 §2.6.1). Extends the abstract Resource type.
Directory: A directory service associated with a Card (RFC 9553 §2.6.2).
EmailAddress: An email address (RFC 9553 §2.3.1).
FilterOperator: Generic filter algebra from jmap-types::query (RFC 8620 §5.5).
LanguagePref: A preferred language (RFC 9553 §2.3.4).
Link: A generic resource link associated with a Card (RFC 9553 §2.6.3).
Media: A media resource associated with a Card (RFC 9553 §2.6.4).
Name: The name of the entity represented by a Card (RFC 9553 §2.2.1).
NameComponent: A single component of a Name (RFC 9553 §2.2.1.2).
Nickname: A nickname for the entity represented by a Card (RFC 9553 §2.2.2).
Note: A free-text note associated with a Card (RFC 9553 §2.8.3).
OnlineService: An online service (messaging service, social media, etc.) (RFC 9553 §2.3.2).
OrgUnit: An organizational unit within an Organization (RFC 9553 §2.2.3).
Organization: A company or organization name associated with a Card (RFC 9553 §2.2.3).
PartialDate: A complete or partial Gregorian calendar date (RFC 9553 §2.8.1).
PersonalInfo: Personal information such as an expertise, hobby, or interest (RFC 9553 §2.8.4).
Phone: A phone number (RFC 9553 §2.3.3).
Pronouns: A pronouns entry (RFC 9553 §2.2.4).
Relation: A relationship to another Card (RFC 9553 §2.1.8).
SchedulingAddress: An iTIP scheduling address (RFC 9553 §2.4.2).
SpeakToAs: How to address or refer to the entity represented by a Card (RFC 9553 §2.2.4).
Timestamp: A UTC point in time (RFC 9553 §2.8.1).
Title: A job title or functional position (RFC 9553 §2.2.5).

Enums§

AnniversaryDate: The date value of an Anniversary — either a PartialDate or a Timestamp (RFC 9553 §2.8.1).
Filter: Generic filter algebra from jmap-types::query (RFC 8620 §5.5).
Operator: Generic filter algebra from jmap-types::query (RFC 8620 §5.5).