Add embed helper methods and docs (#54)

disagreement/models.py

@@ -541,8 +541,42 @@ class Embed:
             payload["fields"] = [f.to_dict() for f in self.fields]
         return payload
 
-    # Convenience methods for building embeds can be added here
+    # Convenience methods mirroring ``discord.py``'s ``Embed`` API
-    # e.g., set_author, add_field, set_footer, set_image, etc.
+
+    def set_author(
+        self, *, name: str, url: Optional[str] = None, icon_url: Optional[str] = None
+    ) -> "Embed":
+        """Set the embed author and return ``self`` for chaining."""
+
+        data: Dict[str, Any] = {"name": name}
+        if url:
+            data["url"] = url
+        if icon_url:
+            data["icon_url"] = icon_url
+        self.author = EmbedAuthor(data)
+        return self
+
+    def add_field(self, *, name: str, value: str, inline: bool = False) -> "Embed":
+        """Add a field to the embed."""
+
+        field = EmbedField({"name": name, "value": value, "inline": inline})
+        self.fields.append(field)
+        return self
+
+    def set_footer(self, *, text: str, icon_url: Optional[str] = None) -> "Embed":
+        """Set the embed footer."""
+
+        data: Dict[str, Any] = {"text": text}
+        if icon_url:
+            data["icon_url"] = icon_url
+        self.footer = EmbedFooter(data)
+        return self
+
+    def set_image(self, url: str) -> "Embed":
+        """Set the embed image."""
+
+        self.image = EmbedImage({"url": url})
+        return self
 
 
 class Attachment:

docs/embeds.md

@@ -0,0 +1,22 @@
+# Embeds
+
+`Embed` objects can be constructed piece by piece much like in `discord.py`.
+These helper methods return the embed instance so you can chain calls.
+
+```python
+from disagreement.models import Embed
+
+embed = (
+    Embed()
+    .set_author(name="Disagreement", url="https://example.com", icon_url="https://cdn.example.com/bot.png")
+    .add_field(name="Info", value="Some details")
+    .set_footer(text="Made with Disagreement")
+    .set_image(url="https://cdn.example.com/image.png")
+)
+```
+
+Call `to_dict()` to convert the embed back to a payload dictionary before sending:
+
+```python
+payload = embed.to_dict()
+```

tests/test_embed_methods.py

@@ -0,0 +1,18 @@
+from disagreement.models import Embed
+
+
+def test_embed_helper_methods():
+    embed = (
+        Embed()
+        .set_author(name="name", url="url", icon_url="icon")
+        .add_field(name="n", value="v")
+        .set_footer(text="footer", icon_url="icon")
+        .set_image(url="https://example.com/image.png")
+    )
+
+    assert embed.author.name == "name"
+    assert embed.author.url == "url"
+    assert embed.author.icon_url == "icon"
+    assert len(embed.fields) == 1 and embed.fields[0].name == "n"
+    assert embed.footer.text == "footer"
+    assert embed.image.url == "https://example.com/image.png"