release/v1.0.0 (#146)

Author: drish

CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-10-31
+
+### Overview
+
+This major release introduces breaking changes to the Contacts API and deprecates the Audiences API in favor of Segments. **If you only use the SDK for sending emails or the Audiences API, you can upgrade to v1.0.0 without any code changes.** The breaking changes are limited to the Contacts API only.
+
+### ⚠️ BREAKING CHANGES
+
+#### Contacts API Changes
+
+- ⚠️ **Change `Contacts.create` to accept hash parameter with optional `audience_id`** - Previously required `audience_id` in params, now it's optional. Supports global contacts.
+- ⚠️ **Change `Contacts.get` from `get(audience_id, id)` to `get(params)`** - Now accepts a hash with optional `audience_id` and required `id` or `email`. Raises `ArgumentError: "Missing \`id\` or \`email\` field"` when neither is provided.
+- ⚠️ **Change `Contacts.list` from `list(audience_id, params = {})` to `list(params = {})`** - Now accepts a hash with optional `audience_id` and pagination params
+- ⚠️ **Change `Contacts.remove` from `remove(audience_id, contact_id)` to `remove(params)`** - Now accepts a hash with optional `audience_id` and required `id` or `email`. Raises `ArgumentError: "Missing \`id\` or \`email\` field"` when neither is provided.
+- ⚠️ **Change `Contacts.update` error message** - Error changed from `"id or email is required"` to `"Missing \`id\` or \`email\` field"` to match Node.js SDK format
+- ⚠️ **Change `Contacts.update` to accept optional `audience_id`** - Previously required `audience_id` in params, now it's optional
+
+**Before (v0.x):**
+
+```ruby
+# Methods used positional arguments and required audience_id
+Resend::Contacts.create(audience_id: "aud_123", email: "user@example.com", first_name: "John")
+contact = Resend::Contacts.get("aud_123", "contact_123")
+contacts = Resend::Contacts.list("aud_123")
+contacts = Resend::Contacts.list("aud_123", limit: 10)
+Resend::Contacts.update(audience_id: "aud_123", id: "contact_123", first_name: "Jane")
+Resend::Contacts.remove("aud_123", "contact_123")
+```
+
+**After (v1.0.0):**
+
+```ruby
+# Methods use hash parameters and support optional audience_id
+# Global contacts (no audience_id)
+Resend::Contacts.create(email: "user@example.com", first_name: "John")
+contact = Resend::Contacts.get(id: "contact_123")
+contact = Resend::Contacts.get(email: "user@example.com")
+contacts = Resend::Contacts.list
+contacts = Resend::Contacts.list(limit: 10)
+Resend::Contacts.update(id: "contact_123", first_name: "Jane")
+Resend::Contacts.remove(id: "contact_123")
+
+# Audience-scoped contacts (with audience_id)
+Resend::Contacts.create(audience_id: "aud_123", email: "user@example.com", first_name: "John")
+contact = Resend::Contacts.get(audience_id: "aud_123", id: "contact_123")
+contacts = Resend::Contacts.list(audience_id: "aud_123", limit: 10)
+Resend::Contacts.update(audience_id: "aud_123", id: "contact_123", first_name: "Jane")
+Resend::Contacts.remove(audience_id: "aud_123", id: "contact_123")
+```
+
+#### Audiences API Deprecated
+
+- ⚠️ **Deprecate `Resend::Audiences` in favor of `Resend::Segments`** - The Audiences module has been replaced with Segments. A backward-compatible alias `Audiences = Segments` has been added, so existing code will continue to work.
+
+**Migration (Recommended):**
+
+Update your code to use `Segments` instead of `Audiences`:
+
+```ruby
+# Before (still works but deprecated)
+Resend::Audiences.create(name: "My Audience")
+Resend::Audiences.get("audience_123")
+Resend::Audiences.list
+Resend::Audiences.remove("audience_123")
+
+# After (recommended)
+Resend::Segments.create(name: "My Segment")
+Resend::Segments.get("segment_123")
+Resend::Segments.list
+Resend::Segments.remove("segment_123")
+```
+
+**Note:** The `Audiences` alias is deprecated and may be removed in a future major version. Please migrate to `Segments`.
+
+### Added
+
+#### New API Modules
+
+- Add `Resend::Templates` API for managing email templates
+  - `Templates.create` - Create a new template
+  - `Templates.get` - Retrieve a template by ID
+  - `Templates.update` - Update an existing template
+  - `Templates.publish` - Publish a template
+  - `Templates.duplicate` - Duplicate an existing template
+  - `Templates.list` - List all templates with pagination
+  - `Templates.remove` - Delete a template
+- Add `Resend::Topics` API for managing topics
+  - `Topics.create` - Create a new topic
+  - `Topics.get` - Retrieve a topic by ID
+  - `Topics.update` - Update a topic
+  - `Topics.list` - List all topics with pagination
+  - `Topics.remove` - Delete a topic
+- Add `Resend::Segments` API for managing segments (replacement for Audiences)
+  - `Segments.create` - Create a new segment
+  - `Segments.get` - Retrieve a segment by ID
+  - `Segments.list` - List all segments
+  - `Segments.remove` - Delete a segment
+- Add `Resend::ContactProperties` API for managing custom contact properties
+  - `ContactProperties.update` - Update contact properties (validates and raises `ArgumentError: "Missing \`id\` field"` when id is not provided)
+  - `ContactProperties.get` - Retrieve contact properties by ID
+- Add `Resend::Contacts::Segments` API for managing contact-segment relationships
+  - `Contacts::Segments.list` - List all segments for a contact
+  - `Contacts::Segments.add` - Add a contact to a segment
+  - `Contacts::Segments.remove` - Remove a contact from a segment
+- Add `Resend::Contacts::Topics` API for managing contact topic subscriptions
+  - `Contacts::Topics.list` - List topic subscriptions for a contact
+  - `Contacts::Topics.update` - Update topic subscriptions (opt-in/opt-out) for a contact
+
+#### Contacts API Enhancements
+
+- Add support for `email` parameter in `Contacts.get` and `Contacts.remove` methods (can now use email instead of ID)
+- Add `audience_id` support in Contacts API methods for scoped operations
+- Add support for global contacts (contacts not scoped to a specific audience/segment)
+- Add validation error messages matching Node.js SDK format with backticks around field names
+
+#### Broadcasts API Updates
+
+- Add deprecation warnings for `audience_id` in `Broadcasts.create` and `Broadcasts.update` (use `segment_id` instead)
+
+### Removed
+
+- Remove deprecated `send_email` method from `Resend::Emails` module (use `Resend::Emails.send` instead)
+
+[1.0.0]: https://github.com/resend/resend-ruby/compare/v0.26.0...v1.0.0

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    resend (0.26.0)
+    resend (1.0.0)
       httparty (>= 0.21.0)
 
 GEM

examples/audiences.rb

@@ -6,20 +6,39 @@
 
 Resend.api_key = ENV["RESEND_API_KEY"]
 
-# replace with an existing audience id
-audience_id = "78b8d3bc-a55a-45a3-aee6-6ec0a5e13d7e"
+# replace with an existing segment id
+segment_id = "78b8d3bc-a55a-45a3-aee6-6ec0a5e13d7e"
 
 create_params = {
   from: "onboarding@resend.dev",
   subject: "Hello from Ruby SDK",
-  audience_id: audience_id,
+  segment_id: segment_id,
   text: "Hello, how are you?",
   name: "Hello from Ruby SDK",
 }
 
 broadcast = Resend::Broadcasts.create(create_params)
 puts "created broadcast: #{broadcast[:id]}"
 
+# Example using deprecated audience_id (still works for backwards compatibility)
+create_params_deprecated = {
+  from: "onboarding@resend.dev",
+  subject: "Hello from Ruby SDK (deprecated audience_id)",
+  audience_id: segment_id, # deprecated: use segment_id instead
+  text: "This example shows audience_id still works",
+  name: "Broadcast with deprecated audience_id",
+}
+
+broadcast_deprecated = Resend::Broadcasts.create(create_params_deprecated)
+puts "created broadcast with deprecated audience_id: #{broadcast_deprecated[:id]}"
+
+# Clean up the deprecated example if it's in draft status
+retrieved_deprecated = Resend::Broadcasts.get(broadcast_deprecated[:id])
+if retrieved_deprecated[:status] == 'draft'
+  Resend::Broadcasts.remove(broadcast_deprecated[:id])
+  puts "removed deprecated example broadcast: #{broadcast_deprecated[:id]}"
+end
+
 update_params = {
   broadcast_id: broadcast[:id],
   name: "Hello from Ruby SDK - updated",
@@ -39,10 +58,16 @@
 broadcasts = Resend::Broadcasts.list
 puts broadcasts
 
-# Example with pagination
-paginated_broadcasts = Resend::Broadcasts.list({ limit: 15, after: "broadcast_id_here" })
-puts "Paginated broadcasts (limit 15, after broadcast_id_here):"
-puts paginated_broadcasts
+# Example with pagination - only demonstrate if has_more is true
+if broadcasts[:has_more]
+  # In real usage, you'd use the cursor from the previous response
+  # For this example, we just show pagination with limit
+  paginated_broadcasts = Resend::Broadcasts.list({ limit: 5 })
+  puts "\nPaginated broadcasts (limit 5):"
+  puts paginated_broadcasts
+else
+  puts "\nNo more broadcasts to paginate through"
+end
 
 retrieved = Resend::Broadcasts.get(broadcast[:id])
 puts "retrieved #{retrieved[:id]}"

examples/broadcasts.rb

@@ -7,7 +7,6 @@
 Resend.api_key = ENV["RESEND_API_KEY"]
 
 def example
-  # Create a contact property with string type
   puts "Creating a string contact property..."
   string_property = Resend::ContactProperties.create({
     key: "company_name",
@@ -18,7 +17,6 @@ def example
 
   property_id = string_property[:id]
 
-  # Create a contact property with number type
   puts "\nCreating a number contact property..."
   number_property = Resend::ContactProperties.create({
     key: "age",
@@ -27,30 +25,25 @@ def example
   })
   puts "Created property: #{number_property}"
 
-  # Retrieve a contact property
   puts "\nRetrieving contact property by ID..."
   retrieved_property = Resend::ContactProperties.get(property_id)
   puts "Retrieved property: #{retrieved_property}"
 
-  # List all contact properties
   puts "\nListing all contact properties..."
   all_properties = Resend::ContactProperties.list
   puts "All properties: #{all_properties}"
 
-  # List contact properties with pagination
   puts "\nListing contact properties with pagination..."
   paginated_properties = Resend::ContactProperties.list({ limit: 10 })
   puts "Paginated properties: #{paginated_properties}"
 
-  # Update a contact property
   puts "\nUpdating contact property..."
   updated_property = Resend::ContactProperties.update({
     id: property_id,
     fallback_value: "Example Company"
   })
   puts "Updated property: #{updated_property}"
 
-  # Delete a contact property
   puts "\nDeleting contact property..."
   deleted = Resend::ContactProperties.remove(property_id)
   puts "Deleted property: #{deleted}"

examples/contact_properties.rb

@@ -29,22 +29,22 @@ def example
     first_name: "Updated",
   }
 
-  retrieved = Resend::Contacts.get(audience_id, contact[:id])
+  retrieved = Resend::Contacts.get(id: contact[:id], audience_id: audience_id)
   puts "Retrived contact by ID"
   puts retrieved
 
-  retrieved_by_email = Resend::Contacts.get(audience_id, contact[:email])
+  retrieved_by_email = Resend::Contacts.get(email: params[:email], audience_id: audience_id)
   puts "Retrived contact by Email"
   puts retrieved_by_email
 
   updated = Resend::Contacts.update(update_params)
   puts "Updated contact: #{updated}"
 
-  contacts = Resend::Contacts.list(audience_id)
+  contacts = Resend::Contacts.list(audience_id: audience_id)
   puts contacts
 
   # Example with pagination
-  paginated_contacts = Resend::Contacts.list(audience_id, { limit: 10 })
+  paginated_contacts = Resend::Contacts.list(audience_id: audience_id, limit: 10)
   puts "Paginated contacts (limit 10):"
   puts paginated_contacts
 
@@ -62,9 +62,9 @@ def example
   puts "Topic created: #{topic}"
   topic_id = topic[:id]
 
-  # Get contact topics
-  puts "\nGetting contact topics..."
-  contact_topics = Resend::Contacts::Topics.get(contact[:id])
+  # List contact topics
+  puts "\nListing contact topics..."
+  contact_topics = Resend::Contacts::Topics.list(id: contact[:id])
   puts "Contact topics: #{contact_topics}"
 
   # Update contact topic subscriptions - opt in to the topic
@@ -79,9 +79,9 @@ def example
   updated_topics = Resend::Contacts::Topics.update(update_topics_params)
   puts "Updated topic subscription: #{updated_topics}"
 
-  # Get contact topics again to see the updated subscription
-  puts "\nGetting contact topics after opt-in..."
-  contact_topics_after = Resend::Contacts::Topics.get(contact[:id])
+  # List contact topics again to see the updated subscription
+  puts "\nListing contact topics after opt-in..."
+  contact_topics_after = Resend::Contacts::Topics.list(id: contact[:id])
   puts "Contact topics after update: #{contact_topics_after}"
 
   # Update contact topic subscriptions - opt out from the topic
@@ -99,10 +99,10 @@ def example
   puts "Topic deleted"
 
   # delete by id
-  del = Resend::Contacts.remove(audience_id, contact[:id])
+  del = Resend::Contacts.remove(id: contact[:id], audience_id: audience_id)
 
   # delete by email
-  # del = Resend::Contacts.remove(audience_id, "steve@example.com")
+  # del = Resend::Contacts.remove(email: "steve@example.com", audience_id: audience_id)
 
   puts "Deleted #{del}"
 end