feature: Added document builder

Signed-off-by: Nick Gerakines <[e-mail]>

crates/atproto-identity/src/model.rs

···
 #[derive(Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct Document {
+    /// JSON-LD context URLs defining the semantics of the DID document.
+    /// Typically includes "https://www.w3.org/ns/did/v1" and method-specific contexts.
+    #[serde(rename = "@context", default)]
+    pub context: Vec<String>,
+
     /// The DID identifier (e.g., "did:plc:abc123").
     pub id: String,
     /// Alternative identifiers like handles and domains.
···
     pub extra: HashMap<String, Value>,
 }
 
+/// Builder for constructing DID documents with a fluent API.
+/// Provides controlled construction with validation capabilities.
+#[derive(Default)]
+pub struct DocumentBuilder {
+    context: Option<Vec<String>>,
+    id: Option<String>,
+    also_known_as: Vec<String>,
+    service: Vec<Service>,
+    verification_method: Vec<VerificationMethod>,
+    extra: HashMap<String, Value>,
+}
+
+impl DocumentBuilder {
+    /// Creates a new DocumentBuilder with empty fields.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Sets the JSON-LD context URLs for the document.
+    pub fn context(mut self, context: Vec<String>) -> Self {
+        self.context = Some(context);
+        self
+    }
+
+    /// Adds a single context URL to the document.
+    pub fn add_context(mut self, context_url: impl Into<String>) -> Self {
+        self.context
+            .get_or_insert_with(|| vec!["https://www.w3.org/ns/did/v1".to_string()])
+            .push(context_url.into());
+        self
+    }
+
+    /// Sets the DID identifier for the document.
+    pub fn id(mut self, id: impl Into<String>) -> Self {
+        self.id = Some(id.into());
+        self
+    }
+
+    /// Sets all alternative identifiers at once.
+    pub fn also_known_as(mut self, aliases: Vec<String>) -> Self {
+        self.also_known_as = aliases;
+        self
+    }
+
+    /// Adds a single alternative identifier.
+    pub fn add_also_known_as(mut self, alias: impl Into<String>) -> Self {
+        self.also_known_as.push(alias.into());
+        self
+    }
+
+    /// Sets all services at once.
+    pub fn services(mut self, services: Vec<Service>) -> Self {
+        self.service = services;
+        self
+    }
+
+    /// Adds a single service to the document.
+    pub fn add_service(mut self, service: Service) -> Self {
+        self.service.push(service);
+        self
+    }
+
+    /// Convenience method to add a PDS service.
+    pub fn add_pds_service(mut self, endpoint: impl Into<String>) -> Self {
+        self.service.push(Service {
+            id: "#atproto_pds".to_string(),
+            r#type: "AtprotoPersonalDataServer".to_string(),
+            service_endpoint: endpoint.into(),
+            extra: HashMap::new(),
+        });
+        self
+    }
+
+    /// Sets all verification methods at once.
+    pub fn verification_methods(mut self, methods: Vec<VerificationMethod>) -> Self {
+        self.verification_method = methods;
+        self
+    }
+
+    /// Adds a single verification method.
+    pub fn add_verification_method(mut self, method: VerificationMethod) -> Self {
+        self.verification_method.push(method);
+        self
+    }
+
+    /// Convenience method to add a Multikey verification method.
+    pub fn add_multikey(
+        mut self,
+        id: impl Into<String>,
+        controller: impl Into<String>,
+        public_key_multibase: impl Into<String>,
+    ) -> Self {
+        let key_multibase = public_key_multibase.into();
+        let key_multibase = key_multibase
+            .strip_prefix("did:key:")
+            .unwrap_or(&key_multibase)
+            .to_string();
+        
+        self.verification_method.push(VerificationMethod::Multikey {
+            id: id.into(),
+            controller: controller.into(),
+            public_key_multibase: key_multibase,
+            extra: HashMap::new(),
+        });
+        self
+    }
+
+    /// Adds an extra property to the document.
+    pub fn add_extra(mut self, key: impl Into<String>, value: Value) -> Self {
+        self.extra.insert(key.into(), value);
+        self
+    }
+
+    /// Builds the Document, returning an error if required fields are missing.
+    pub fn build(self) -> Result<Document, &'static str> {
+        let id = self.id.ok_or("Document ID is required")?;
+        
+        // Use default context if not provided
+        let context = self.context.unwrap_or_else(|| {
+            vec!["https://www.w3.org/ns/did/v1".to_string()]
+        });
+
+        Ok(Document {
+            context,
+            id,
+            also_known_as: self.also_known_as,
+            service: self.service,
+            verification_method: self.verification_method,
+            extra: self.extra,
+        })
+    }
+}
+
 impl Document {
+    /// Creates a new DocumentBuilder for constructing a Document.
+    pub fn builder() -> DocumentBuilder {
+        DocumentBuilder::new()
+    }
+
     /// Extracts Personal Data Server endpoints from services.
     /// Returns URLs of all AtprotoPersonalDataServer services.
     pub fn pds_endpoints(&self) -> Vec<&str> {
···
 
 #[cfg(test)]
 mod tests {
-    use crate::model::Document;
+    use crate::model::{Document, Service};
+    use std::collections::HashMap;
 
     #[test]
     fn test_deserialize() {
···
 
         let document = document.unwrap();
         assert_eq!(document.id, "did:plc:cbkjy5n7bk3ax2wplmtjofq2");
+    }
+
+    #[test]
+    fn test_document_builder() {
+        // Test basic builder
+        let doc = Document::builder()
+            .id("did:plc:test123")
+            .build()
+            .expect("Should build with just ID");
+        
+        assert_eq!(doc.id, "did:plc:test123");
+        assert_eq!(doc.context, vec!["https://www.w3.org/ns/did/v1"]);
+        assert!(doc.also_known_as.is_empty());
+        assert!(doc.service.is_empty());
+        assert!(doc.verification_method.is_empty());
+    }
+
+    #[test]
+    fn test_document_builder_full() {
+        let doc = Document::builder()
+            .id("did:plc:test123")
+            .add_context("https://w3id.org/security/multikey/v1")
+            .add_also_known_as("at://test.bsky.social")
+            .add_also_known_as("https://test.example.com")
+            .add_pds_service("https://pds.example.com")
+            .add_multikey(
+                "did:plc:test123#atproto",
+                "did:plc:test123",
+                "zQ3shXvCK2RyPrSLYQjBEw5CExZkUhJH3n1K2Mb9sC7JbvRMF",
+            )
+            .build()
+            .expect("Should build complete document");
+        
+        assert_eq!(doc.id, "did:plc:test123");
+        assert_eq!(doc.context.len(), 2);
+        assert_eq!(doc.also_known_as.len(), 2);
+        assert_eq!(doc.service.len(), 1);
+        assert_eq!(doc.service[0].r#type, "AtprotoPersonalDataServer");
+        assert_eq!(doc.verification_method.len(), 1);
+        
+        // Test PDS endpoint extraction
+        let pds_endpoints = doc.pds_endpoints();
+        assert_eq!(pds_endpoints.len(), 1);
+        assert_eq!(pds_endpoints[0], "https://pds.example.com");
+    }
+
+    #[test]
+    fn test_document_builder_with_service() {
+        let service = Service {
+            id: "#custom".to_string(),
+            r#type: "CustomService".to_string(),
+            service_endpoint: "https://custom.example.com".to_string(),
+            extra: HashMap::new(),
+        };
+        
+        let doc = Document::builder()
+            .id("did:web:example.com")
+            .add_service(service)
+            .build()
+            .expect("Should build with custom service");
+        
+        assert_eq!(doc.service.len(), 1);
+        assert_eq!(doc.service[0].r#type, "CustomService");
+    }
+
+    #[test]
+    fn test_document_builder_missing_id() {
+        let result = Document::builder()
+            .add_also_known_as("at://test.bsky.social")
+            .build();
+        
+        assert!(result.is_err());
+        assert_eq!(result.unwrap_err(), "Document ID is required");
+    }
+
+    #[test]
+    fn test_document_builder_with_extra() {
+        let doc = Document::builder()
+            .id("did:plc:test123")
+            .add_extra("customField", serde_json::json!("customValue"))
+            .add_extra("numberField", serde_json::json!(42))
+            .build()
+            .expect("Should build with extra fields");
+        
+        assert_eq!(doc.extra.len(), 2);
+        assert_eq!(doc.extra.get("customField").unwrap(), &serde_json::json!("customValue"));
+        assert_eq!(doc.extra.get("numberField").unwrap(), &serde_json::json!(42));
     }
 
     #[test]

crates/atproto-identity/src/storage_lru.rs

···
 ///
 /// // Create a sample document
 /// let document = Document {
+///     context: vec![],
 ///     id: "did:plc:bv6ggog3tya2z3vxsub7hnal".to_string(),
 ///     also_known_as: vec!["at://alice.bsky.social".to_string()],
 ///     service: vec![], // simplified for example
···
     /// assert_eq!(storage.len(), 0);
     ///
     /// let doc1 = Document {
+    ///     context: vec![],
     ///     id: "did:plc:example1".to_string(),
     ///     also_known_as: vec![],
     ///     service: vec![],
···
     /// assert_eq!(storage.len(), 1);
     ///
     /// let doc2 = Document {
+    ///     context: vec![],
     ///     id: "did:plc:example2".to_string(),
     ///     also_known_as: vec![],
     ///     service: vec![],
···
     /// # tokio::runtime::Runtime::new().unwrap().block_on(async {
     /// let storage = LruDidDocumentStorage::new(NonZeroUsize::new(100).unwrap());
     /// let document = Document {
+    ///     context: vec![],
     ///     id: "did:plc:example".to_string(),
     ///     also_known_as: vec![],
     ///     service: vec![],
···
     ///
     /// // Add document to cache
     /// let doc = Document {
+    ///     context: vec![],
     ///     id: "did:plc:bv6ggog3tya2z3vxsub7hnal".to_string(),
     ///     also_known_as: vec!["at://alice.bsky.social".to_string()],
     ///     service: vec![],
···
     ///
     /// // Add first document
     /// let doc1 = Document {
+    ///     context: vec![],
     ///     id: "did:plc:user1".to_string(),
     ///     also_known_as: vec!["at://alice.bsky.social".to_string()],
     ///     service: vec![],
···
     ///
     /// // Add second document
     /// let doc2 = Document {
+    ///     context: vec![],
     ///     id: "did:plc:user2".to_string(),
     ///     also_known_as: vec!["at://bob.bsky.social".to_string()],
     ///     service: vec![],
···
     ///
     /// // Add third document - this will evict the least recently used entry (user1)
     /// let doc3 = Document {
+    ///     context: vec![],
     ///     id: "did:plc:user3".to_string(),
     ///     also_known_as: vec!["at://charlie.bsky.social".to_string()],
     ///     service: vec![],
···
     ///
     /// // Add a document
     /// let document = Document {
+    ///     context: vec![],
     ///     id: "did:plc:bv6ggog3tya2z3vxsub7hnal".to_string(),
     ///     also_known_as: vec!["at://alice.bsky.social".to_string()],
     ///     service: vec![],
···
 
     fn create_test_document(did: &str, handle: &str) -> Document {
         Document {
+            context: vec![],
             id: did.to_string(),
             also_known_as: vec![format!("at://{}", handle)],
             service: vec![],
···
 
         // Create a document with complex content
         let mut complex_document = Document {
+            context: vec![],
             id: "did:plc:complex".to_string(),
             also_known_as: vec![
                 "at://alice.bsky.social".to_string(),

crates/atproto-xrpcs/src/authorization.rs

···
         let verification_method_id = "did:key:zQ3shXvCK2RyPrSLYQjBEw5CExZkUhJH3n1K2Mb9sC7JbvRMF";
 
         let document = Document {
+            context: vec![],
             id: did.to_string(),
             also_known_as: vec![],
             service: vec![],
···
         // Create mock storage
         let storage = Arc::new(MockStorage {
             document: Document {
+                context: vec![],
                 id: "did:plc:test".to_string(),
                 also_known_as: vec![],
                 service: vec![],