surge_api 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 614370dfa43aa94b2c07f29576b6e5859d11010ede1baa50269ff5d2d1ceccc9
-  data.tar.gz: a1717cedfe90b25cb8ad1c6fc529bd89ed6bead53039a37c0c1d99883fae1b42
+  metadata.gz: dcd65a3f11b5c187dcefe5f82f90dfef4bb4421e06115246ccda187f459e9202
+  data.tar.gz: c8bac9291bc751a4ddfdb952f70eb32fcb696ef886a5c3521f149e7235f18733
 SHA512:
-  metadata.gz: 139587949698301477b68cb7a99f4b3367bc9575369ba153bb318f94dc488120348fb19a0ec2d566fd0407ddada88cddbfbf8ad1ac26640685e052408e29b6c4
-  data.tar.gz: 53b59055a002e7720fe165241c3ef0df906657d900dcb729da9be4a06e93a947a407eb7d73816a4aa76dac178e885f321f9528169e39f9ec719e4ab60fa27da1
+  metadata.gz: '0032493ed7b14b18fc06f216c37ed91814fbd61874e777604013cde0c694859767b177820dc298559024a9a2c7f39d878157e7e6b24035fce20ad07fa1b984e0'
+  data.tar.gz: abe1e0ff490003f4f4376847989c4b0f982abb34ac3eae1bc308b81abf22a03e4078dd08d49c23db58a91e271831d450fe2087938286455fcc381d126602a14c

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.17.0 (2026-05-04)
+
+Full Changelog: [v0.16.0...v0.17.0](https://github.com/surgeapi/ruby-sdk/compare/v0.16.0...v0.17.0)
+
+### Features
+
+* **api:** list accounts endpoint ([510b3bc](https://github.com/surgeapi/ruby-sdk/commit/510b3bc3d2ab9b8659e5ca0701cef8fc2c5f2a2e))
+
+## 0.16.0 (2026-04-22)
+
+Full Changelog: [v0.15.0...v0.16.0](https://github.com/surgeapi/ruby-sdk/compare/v0.15.0...v0.16.0)
+
+### Features
+
+* **api:** add endpoint to get attachment file ([5475d91](https://github.com/surgeapi/ruby-sdk/commit/5475d91e283e6afb974243f11a259e9990471f88))
+* **api:** add message to link.followed events ([1c36d5c](https://github.com/surgeapi/ruby-sdk/commit/1c36d5c6c21eb866aa5489ce0b70b01bfd01a9e4))
+* **api:** add name to phone numbers ([ee71d0d](https://github.com/surgeapi/ruby-sdk/commit/ee71d0dcec71388ed0af4132759072cca94e11f0))
+
 ## 0.15.0 (2026-04-06)
 
 Full Changelog: [v0.14.0...v0.15.0](https://github.com/surgeapi/ruby-sdk/compare/v0.14.0...v0.15.0)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "surge_api", "~> 0.15.0"
+gem "surge_api", "~> 0.17.0"
 ```
 
 <!-- x-release-please-end -->
@@ -44,15 +44,15 @@ List methods in the Surge API are paginated.
 This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
 
 ```ruby
-page = surge.audiences.list_contacts
+page = surge.accounts.list
 
 # Fetch single item from page.
-audience = page.data[0]
-puts(audience.id)
+account = page.data[0]
+puts(account.id)
 
 # Automatically fetches more pages as needed.
-page.auto_paging_each do |audience|
-  puts(audience.id)
+page.auto_paging_each do |account|
+  puts(account.id)
 end
 ```
 

data/lib/surge_api/client.rb

@@ -21,6 +21,9 @@ module SurgeAPI
     # @return [SurgeAPI::Resources::Accounts]
     attr_reader :accounts
 
+    # @return [SurgeAPI::Resources::Attachments]
+    attr_reader :attachments
+
     # @return [SurgeAPI::Resources::Audiences]
     attr_reader :audiences
 
@@ -99,6 +102,7 @@ module SurgeAPI
       )
 
       @accounts = SurgeAPI::Resources::Accounts.new(client: self)
+      @attachments = SurgeAPI::Resources::Attachments.new(client: self)
       @audiences = SurgeAPI::Resources::Audiences.new(client: self)
       @blasts = SurgeAPI::Resources::Blasts.new(client: self)
       @campaigns = SurgeAPI::Resources::Campaigns.new(client: self)

data/lib/surge_api/internal/cursor.rb

@@ -10,8 +10,8 @@ module SurgeAPI
     #   end
     #
     # @example
-    #   cursor.auto_paging_each do |audience|
-    #     puts(audience)
+    #   cursor.auto_paging_each do |account|
+    #     puts(account)
     #   end
     class Cursor
       include SurgeAPI::Internal::Type::BasePage

data/lib/surge_api/models/account_list_params.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::Accounts#list
+    class AccountListParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!attribute after
+      #   Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @return [String, nil]
+      optional :after, String
+
+      # @!attribute before
+      #   Cursor for backward pagination. Use the previous_cursor from a previous
+      #   response.
+      #
+      #   @return [String, nil]
+      optional :before, String
+
+      # @!method initialize(after: nil, before: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {SurgeAPI::Models::AccountListParams} for more details.
+      #
+      #   @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/surge_api/models/attachment_get_file_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::Attachments#get_file
+    class AttachmentGetFileParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/surge_api/models/attachment_get_file_response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::Attachments#get_file
+    class AttachmentGetFileResponse < SurgeAPI::Internal::Type::BaseModel
+      # @!attribute error
+      #   An error response
+      #
+      #   @return [SurgeAPI::Models::Error]
+      required :error, -> { SurgeAPI::Error }
+
+      # @!method initialize(error:)
+      #   An error response
+      #
+      #   @param error [SurgeAPI::Models::Error] An error response
+    end
+  end
+end

data/lib/surge_api/models/link_followed_webhook_event.rb

@@ -44,11 +44,19 @@ module SurgeAPI
         #   @return [String]
         required :id, String
 
+        # @!attribute message
+        #   A Message is a communication sent to a Contact.
+        #
+        #   @return [SurgeAPI::Models::Message, nil]
+        required :message, -> { SurgeAPI::Message }, nil?: true
+
         # @!attribute message_id
-        #   The unique identifier for the message that contained the link
+        #   @deprecated Use `message.id` instead.
         #
-        #   @return [String]
-        required :message_id, String
+        #   Deprecated. The unique identifier for the message that contained the link.
+        #
+        #   @return [String, nil]
+        required :message_id, String, nil?: true
 
         # @!attribute url
         #   The original URL that was shortened
@@ -56,12 +64,14 @@ module SurgeAPI
         #   @return [String]
         required :url, String
 
-        # @!method initialize(id:, message_id:, url:)
+        # @!method initialize(id:, message:, message_id:, url:)
         #   The data associated with the event
         #
         #   @param id [String] The unique identifier for the link
         #
-        #   @param message_id [String] The unique identifier for the message that contained the link
+        #   @param message [SurgeAPI::Models::Message, nil] A Message is a communication sent to a Contact.
+        #
+        #   @param message_id [String, nil] Deprecated. The unique identifier for the message that contained the link.
         #
         #   @param url [String] The original URL that was shortened
       end

data/lib/surge_api/models/message.rb

@@ -139,6 +139,12 @@ module SurgeAPI
           #   @return [String]
           required :id, String
 
+          # @!attribute name
+          #   A human-readable name for the phone number
+          #
+          #   @return [String, nil]
+          required :name, String, nil?: true
+
           # @!attribute number
           #   The canonical format of the phone number.
           #
@@ -151,11 +157,13 @@ module SurgeAPI
           #   @return [Symbol, SurgeAPI::Models::Message::Conversation::PhoneNumber::Type]
           required :type, enum: -> { SurgeAPI::Message::Conversation::PhoneNumber::Type }
 
-          # @!method initialize(id:, number:, type:)
+          # @!method initialize(id:, name:, number:, type:)
           #   This is the phone number tied to the Surge account.
           #
           #   @param id [String] Unique identifier for the phone number
           #
+          #   @param name [String, nil] A human-readable name for the phone number
+          #
           #   @param number [String] The canonical format of the phone number.
           #
           #   @param type [Symbol, SurgeAPI::Models::Message::Conversation::PhoneNumber::Type] Whether the phone number is local, toll-free, or short code

data/lib/surge_api/models/phone_number.rb

@@ -16,6 +16,12 @@ module SurgeAPI
       #   @return [String, nil]
       required :campaign_id, String, nil?: true
 
+      # @!attribute name
+      #   A human-readable name for the phone number
+      #
+      #   @return [String, nil]
+      required :name, String, nil?: true
+
       # @!attribute number
       #   The phone number in E.164 format
       #
@@ -28,13 +34,15 @@ module SurgeAPI
       #   @return [Symbol, SurgeAPI::Models::PhoneNumber::Type]
       required :type, enum: -> { SurgeAPI::PhoneNumber::Type }
 
-      # @!method initialize(id:, campaign_id:, number:, type:)
+      # @!method initialize(id:, campaign_id:, name:, number:, type:)
       #   A phone number that can be used to send and receive messages and calls
       #
       #   @param id [String] Unique identifier for the phone number
       #
       #   @param campaign_id [String, nil] The unique identifier of the campaign this phone number is attached to, if any
       #
+      #   @param name [String, nil] A human-readable name for the phone number
+      #
       #   @param number [String] The phone number in E.164 format
       #
       #   @param type [Symbol, SurgeAPI::Models::PhoneNumber::Type] Whether the phone number is local, toll-free, or short code

data/lib/surge_api/models/phone_number_attached_to_campaign_webhook_event.rb

@@ -54,6 +54,12 @@ module SurgeAPI
         #   @return [String]
         required :campaign_id, String
 
+        # @!attribute name
+        #   A human-readable name for the phone number
+        #
+        #   @return [String, nil]
+        required :name, String, nil?: true
+
         # @!attribute number
         #   The phone number in E.164 format
         #
@@ -66,13 +72,15 @@ module SurgeAPI
         #   @return [Symbol, SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Type]
         required :type, enum: -> { SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Type }
 
-        # @!method initialize(id:, campaign_id:, number:, type:)
+        # @!method initialize(id:, campaign_id:, name:, number:, type:)
         #   The data associated with the event
         #
         #   @param id [String] The unique identifier for the phone number
         #
         #   @param campaign_id [String] The unique identifier of the campaign this phone number is attached to
         #
+        #   @param name [String, nil] A human-readable name for the phone number
+        #
         #   @param number [String] The phone number in E.164 format
         #
         #   @param type [Symbol, SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Type] Whether the phone number is local, toll-free, or short code

data/lib/surge_api/models/phone_number_purchase_params.rb

@@ -28,6 +28,13 @@ module SurgeAPI
       #   @return [Float, nil]
       optional :longitude, Float
 
+      # @!attribute name
+      #   A human-readable name for the phone number. If not provided, defaults to the
+      #   formatted phone number.
+      #
+      #   @return [String, nil]
+      optional :name, String
+
       # @!attribute type
       #   Whether the phone number is local or toll-free. Can be omitted if area_code or
       #   latitude/longitude are provided.
@@ -35,7 +42,7 @@ module SurgeAPI
       #   @return [Symbol, SurgeAPI::Models::PhoneNumberPurchaseParams::Type, nil]
       optional :type, enum: -> { SurgeAPI::PhoneNumberPurchaseParams::Type }
 
-      # @!method initialize(area_code: nil, latitude: nil, longitude: nil, type: nil, request_options: {})
+      # @!method initialize(area_code: nil, latitude: nil, longitude: nil, name: nil, type: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {SurgeAPI::Models::PhoneNumberPurchaseParams} for more details.
       #
@@ -45,6 +52,8 @@ module SurgeAPI
       #
       #   @param longitude [Float] Longitude to search for nearby phone numbers. Must be used with latitude. If pro
       #
+      #   @param name [String] A human-readable name for the phone number. If not provided, defaults to the for
+      #
       #   @param type [Symbol, SurgeAPI::Models::PhoneNumberPurchaseParams::Type] Whether the phone number is local or toll-free. Can be omitted if area_code or l
       #
       #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]

data/lib/surge_api/models.rb

@@ -45,12 +45,16 @@ module SurgeAPI
 
   AccountCreateParams = SurgeAPI::Models::AccountCreateParams
 
+  AccountListParams = SurgeAPI::Models::AccountListParams
+
   AccountRetrieveStatusParams = SurgeAPI::Models::AccountRetrieveStatusParams
 
   AccountStatus = SurgeAPI::Models::AccountStatus
 
   AccountUpdateParams = SurgeAPI::Models::AccountUpdateParams
 
+  AttachmentGetFileParams = SurgeAPI::Models::AttachmentGetFileParams
+
   AudienceAddContactParams = SurgeAPI::Models::AudienceAddContactParams
 
   AudienceCreateParams = SurgeAPI::Models::AudienceCreateParams

data/lib/surge_api/resources/accounts.rb

@@ -67,6 +67,35 @@ module SurgeAPI
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {SurgeAPI::Models::AccountListParams} for more details.
+      #
+      # List all accounts for the calling platform with cursor-based pagination.
+      #
+      # @overload list(after: nil, before: nil, request_options: {})
+      #
+      # @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      # @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Internal::Cursor<SurgeAPI::Models::Account>]
+      #
+      # @see SurgeAPI::Models::AccountListParams
+      def list(params = {})
+        parsed, options = SurgeAPI::AccountListParams.dump_request(params)
+        query = SurgeAPI::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "accounts",
+          query: query,
+          page: SurgeAPI::Internal::Cursor,
+          model: SurgeAPI::Account,
+          options: options
+        )
+      end
+
       # Archives an account and releases all associated resources.
       #
       # **Warning**: This action will:

data/lib/surge_api/resources/attachments.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Resources
+    class Attachments
+      # Redirects to a signed URL where the attachment file can be downloaded. URL is
+      # short-lived, so redirect should be followed immediately.
+      #
+      # @overload get_file(attachment_id, request_options: {})
+      #
+      # @param attachment_id [String] The ID of the attachment.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::AttachmentGetFileResponse]
+      #
+      # @see SurgeAPI::Models::AttachmentGetFileParams
+      def get_file(attachment_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["attachments/%1$s/file", attachment_id],
+          model: SurgeAPI::Models::AttachmentGetFileResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [SurgeAPI::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/surge_api/resources/phone_numbers.rb

@@ -40,7 +40,7 @@ module SurgeAPI
       # Purchase a new phone number for the account. You can specify search criteria or
       # let the system select a random number.
       #
-      # @overload purchase(account_id, area_code: nil, latitude: nil, longitude: nil, type: nil, request_options: {})
+      # @overload purchase(account_id, area_code: nil, latitude: nil, longitude: nil, name: nil, type: nil, request_options: {})
       #
       # @param account_id [String] The account for which the phone number should be created.
       #
@@ -50,6 +50,8 @@ module SurgeAPI
       #
       # @param longitude [Float] Longitude to search for nearby phone numbers. Must be used with latitude. If pro
       #
+      # @param name [String] A human-readable name for the phone number. If not provided, defaults to the for
+      #
       # @param type [Symbol, SurgeAPI::Models::PhoneNumberPurchaseParams::Type] Whether the phone number is local or toll-free. Can be omitted if area_code or l
       #
       # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]

data/lib/surge_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SurgeAPI
-  VERSION = "0.15.0"
+  VERSION = "0.17.0"
 end

data/lib/surge_api.rb

@@ -58,9 +58,12 @@ require_relative "surge_api/models/message_params"
 require_relative "surge_api/models/account"
 require_relative "surge_api/models/account_archive_params"
 require_relative "surge_api/models/account_create_params"
+require_relative "surge_api/models/account_list_params"
 require_relative "surge_api/models/account_retrieve_status_params"
 require_relative "surge_api/models/account_status"
 require_relative "surge_api/models/account_update_params"
+require_relative "surge_api/models/attachment_get_file_params"
+require_relative "surge_api/models/attachment_get_file_response"
 require_relative "surge_api/models/audience_add_contact_params"
 require_relative "surge_api/models/audience_create_params"
 require_relative "surge_api/models/audience_create_response"
@@ -123,6 +126,7 @@ require_relative "surge_api/models/voicemail_received_webhook_event"
 require_relative "surge_api/models/webhook_unwrap_params"
 require_relative "surge_api/models"
 require_relative "surge_api/resources/accounts"
+require_relative "surge_api/resources/attachments"
 require_relative "surge_api/resources/audiences"
 require_relative "surge_api/resources/blasts"
 require_relative "surge_api/resources/campaigns"

data/rbi/surge_api/client.rbi

@@ -16,6 +16,9 @@ module SurgeAPI
     sig { returns(SurgeAPI::Resources::Accounts) }
     attr_reader :accounts
 
+    sig { returns(SurgeAPI::Resources::Attachments) }
+    attr_reader :attachments
+
     sig { returns(SurgeAPI::Resources::Audiences) }
     attr_reader :audiences
 

data/rbi/surge_api/models/account_list_params.rbi

@@ -0,0 +1,59 @@
+# typed: strong
+
+module SurgeAPI
+  module Models
+    class AccountListParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(SurgeAPI::AccountListParams, SurgeAPI::Internal::AnyHash)
+        end
+
+      # Cursor for forward pagination. Use the next_cursor from a previous response.
+      sig { returns(T.nilable(String)) }
+      attr_reader :after
+
+      sig { params(after: String).void }
+      attr_writer :after
+
+      # Cursor for backward pagination. Use the previous_cursor from a previous
+      # response.
+      sig { returns(T.nilable(String)) }
+      attr_reader :before
+
+      sig { params(before: String).void }
+      attr_writer :before
+
+      sig do
+        params(
+          after: String,
+          before: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Cursor for forward pagination. Use the next_cursor from a previous response.
+        after: nil,
+        # Cursor for backward pagination. Use the previous_cursor from a previous
+        # response.
+        before: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            after: String,
+            before: String,
+            request_options: SurgeAPI::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/surge_api/models/attachment_get_file_params.rbi

@@ -0,0 +1,27 @@
+# typed: strong
+
+module SurgeAPI
+  module Models
+    class AttachmentGetFileParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(SurgeAPI::AttachmentGetFileParams, SurgeAPI::Internal::AnyHash)
+        end
+
+      sig do
+        params(request_options: SurgeAPI::RequestOptions::OrHash).returns(
+          T.attached_class
+        )
+      end
+      def self.new(request_options: {})
+      end
+
+      sig { override.returns({ request_options: SurgeAPI::RequestOptions }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/surge_api/models/attachment_get_file_response.rbi

@@ -0,0 +1,34 @@
+# typed: strong
+
+module SurgeAPI
+  module Models
+    class AttachmentGetFileResponse < SurgeAPI::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            SurgeAPI::Models::AttachmentGetFileResponse,
+            SurgeAPI::Internal::AnyHash
+          )
+        end
+
+      # An error response
+      sig { returns(SurgeAPI::Error) }
+      attr_reader :error
+
+      sig { params(error: SurgeAPI::Error::OrHash).void }
+      attr_writer :error
+
+      # An error response
+      sig { params(error: SurgeAPI::Error::OrHash).returns(T.attached_class) }
+      def self.new(
+        # An error response
+        error:
+      )
+      end
+
+      sig { override.returns({ error: SurgeAPI::Error }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/surge_api/models/link_followed_webhook_event.rbi

@@ -75,8 +75,15 @@ module SurgeAPI
         sig { returns(String) }
         attr_accessor :id
 
-        # The unique identifier for the message that contained the link
-        sig { returns(String) }
+        # A Message is a communication sent to a Contact.
+        sig { returns(T.nilable(SurgeAPI::Message)) }
+        attr_reader :message
+
+        sig { params(message: T.nilable(SurgeAPI::Message::OrHash)).void }
+        attr_writer :message
+
+        # Deprecated. The unique identifier for the message that contained the link.
+        sig { returns(T.nilable(String)) }
         attr_accessor :message_id
 
         # The original URL that was shortened
@@ -85,14 +92,19 @@ module SurgeAPI
 
         # The data associated with the event
         sig do
-          params(id: String, message_id: String, url: String).returns(
-            T.attached_class
-          )
+          params(
+            id: String,
+            message: T.nilable(SurgeAPI::Message::OrHash),
+            message_id: T.nilable(String),
+            url: String
+          ).returns(T.attached_class)
         end
         def self.new(
           # The unique identifier for the link
           id:,
-          # The unique identifier for the message that contained the link
+          # A Message is a communication sent to a Contact.
+          message:,
+          # Deprecated. The unique identifier for the message that contained the link.
           message_id:,
           # The original URL that was shortened
           url:
@@ -100,7 +112,14 @@ module SurgeAPI
         end
 
         sig do
-          override.returns({ id: String, message_id: String, url: String })
+          override.returns(
+            {
+              id: String,
+              message: T.nilable(SurgeAPI::Message),
+              message_id: T.nilable(String),
+              url: String
+            }
+          )
         end
         def to_hash
         end