This is the Sortal library for mapping usernames to contact metadata.

The library follows OCaml best practices with abstract types (type t) per module, comprehensive constructors/accessors, and proper pretty printers. Each core concept gets its own module with a clean interface.

Design Principles#

1. XDG Storage: All contact data is stored in XDG-compliant locations using the xdge library
2. JSON Format: Contact metadata is serialized using jsont for type-safe JSON encoding/decoding
3. Nested Modules: The Contact module is nested within the main Sortal module following the canonical type t pattern
4. One File Per Contact: Each contact is stored as a separate JSON file named "{handle}.json"

Storage Location#

Contact data is stored in the XDG data directory for the application:

• Default: $HOME/.local/share/{app_name}/contacts/
• Can be overridden via ${APP_NAME}_DATA_DIR or XDG_DATA_HOME

Metadata Fields#

The Contact type includes the following metadata fields (all optional except handle and names):

• handle: Unique identifier/username
• names: List of full names (primary name first)
• email: Email address
• icon: Avatar/icon URL
• thumbnail: Path to a local thumbnail image file (stored in thumbnails/ subdirectory)
• github: GitHub username
• twitter: Twitter/X username
• bluesky: Bluesky handle
• mastodon: Mastodon handle (with instance)
• orcid: ORCID identifier
• url: Personal/professional website
• atom_feeds: List of Atom/RSS feed URLs

Thumbnails#

Contact thumbnails are stored locally in the XDG data directory:

• Location: $HOME/.local/share/{app_name}/thumbnails/
• Files are named: {handle}.{jpg|png|gif}
• The thumbnail field contains a relative path like thumbnails/{handle}.jpg