sendly 3.34.0 → 3.37.0

data/lib/sendly/links_resource.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Sendly
+  # A newly minted branded short link, as returned by {LinksResource#create}.
+  class ShortLink
+    # @return [String] Short code (the segment after the domain, e.g. "Ab3xY7")
+    attr_reader :code
+
+    # @return [String] Full branded short URL to share (e.g. "https://sendly.live/l/Ab3xY7")
+    attr_reader :short_url
+
+    # @return [String] The destination the short link redirects to
+    attr_reader :destination_url
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    def initialize(data)
+      @raw = data
+      @code = data["code"]
+      @short_url = data["shortUrl"] || data["short_url"]
+      @destination_url = data["destinationUrl"] || data["destination_url"]
+    end
+
+    def to_h
+      {
+        code: code, short_url: short_url, destination_url: destination_url
+      }.compact
+    end
+  end
+
+  # A short link with click analytics, as returned by {LinksResource#list}.
+  class ShortLinkListItem
+    attr_reader :code, :short_url, :destination_url, :brand_slug, :click_count,
+                :disabled, :last_country, :last_clicked_at, :created_at, :spark
+
+    def initialize(data)
+      @code = data["code"]
+      @short_url = data["shortUrl"] || data["short_url"]
+      @destination_url = data["destinationUrl"] || data["destination_url"]
+      @brand_slug = data["brandSlug"] || data["brand_slug"]
+      @click_count = data["clickCount"] || data["click_count"] || 0
+      @disabled = data["disabled"] || false
+      @last_country = data["lastCountry"] || data["last_country"]
+      @last_clicked_at = parse_time(data["lastClickedAt"] || data["last_clicked_at"])
+      @created_at = parse_time(data["createdAt"] || data["created_at"])
+      # 14-day daily click histogram, oldest first (today last)
+      @spark = data["spark"] || []
+    end
+
+    # @return [Boolean] Whether the link is disabled (its redirect returns 404)
+    def disabled?
+      disabled
+    end
+
+    def to_h
+      {
+        code: code, short_url: short_url, destination_url: destination_url,
+        brand_slug: brand_slug, click_count: click_count, disabled: disabled,
+        last_country: last_country, last_clicked_at: last_clicked_at&.iso8601,
+        created_at: created_at&.iso8601, spark: spark
+      }.compact
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+      Time.parse(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # A page of short links with their click analytics.
+  class ShortLinkList
+    include Enumerable
+
+    # @return [Array<ShortLinkListItem>] The workspace's short links, newest first
+    attr_reader :links
+
+    # @return [Integer] Total number of short links in the workspace
+    attr_reader :total
+
+    def initialize(response)
+      @links = (response["links"] || []).map { |l| ShortLinkListItem.new(l) }
+      @total = response["total"] || @links.length
+    end
+
+    def each(&block)
+      links.each(&block)
+    end
+
+    def count
+      links.length
+    end
+
+    alias size count
+    alias length count
+
+    def empty?
+      links.empty?
+    end
+
+    def first
+      links.first
+    end
+
+    def last
+      links.last
+    end
+  end
+
+  # The code and new disabled state returned when a link's kill switch is toggled.
+  class ShortLinkStatus
+    # @return [String] Short code that was updated
+    attr_reader :code
+
+    # @return [Boolean] New disabled state
+    attr_reader :disabled
+
+    def initialize(data)
+      @code = data["code"]
+      @disabled = data["disabled"] || false
+    end
+
+    # @return [Boolean] Whether the link is now disabled
+    def disabled?
+      disabled
+    end
+
+    def to_h
+      { code: code, disabled: disabled }
+    end
+  end
+
+  # Links resource — branded URL shortening.
+  #
+  # Mint branded short links for a destination URL, list the links your
+  # workspace has created (with click analytics), and enable or disable an
+  # individual link (a per-link kill switch).
+  #
+  # Branded, owned-domain short links improve deliverability — carriers filter
+  # public shorteners — and give you click data.
+  #
+  # NOTE: URL shortening is not yet generally available. It is gated behind the
+  # +url_shortener+ rollout flag (currently founder-only); for API-key clients a
+  # flag-off account reads as a 404 {Sendly::NotFoundError} (the feature is
+  # absent) until the flag is on for your account.
+  #
+  # @example Shorten a URL
+  #   link = client.links.create(url: "https://example.com/spring-sale?utm_source=sms")
+  #   puts link.short_url # => "https://sendly.live/l/Ab3xY7"
+  #
+  # @example List your links with click counts
+  #   result = client.links.list(limit: 20)
+  #   result.each { |l| puts "#{l.short_url} -> #{l.destination_url} (#{l.click_count} clicks)" }
+  #
+  # @example Kill a link
+  #   client.links.disable(link.code)
+  class LinksResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Mint a branded short link for a destination URL. Uses your workspace's
+    # brand slug when one is configured.
+    #
+    # @param url [String] The destination URL to shorten (must be http/https)
+    # @return [Sendly::ShortLink] The short link (code, short_url, destination_url)
+    #
+    # @raise [Sendly::ValidationError] If url is missing or not an http/https URL
+    def create(url:)
+      validate_url!(url)
+
+      response = @client.post("/links", { url: url })
+      ShortLink.new(response)
+    end
+
+    # List the short links your workspace has created, newest first, with click
+    # counts and a 14-day daily click histogram.
+    #
+    # @param limit [Integer, nil] Maximum links to return (default 50, max 200)
+    # @param offset [Integer, nil] Number of links to skip (default 0)
+    # @return [Sendly::ShortLinkList] The links and a total count
+    def list(limit: nil, offset: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:offset] = offset if offset
+
+      response = @client.get("/links", params)
+      ShortLinkList.new(response)
+    end
+
+    # Enable or disable a short link. A disabled link's redirect returns 404
+    # until it is re-enabled.
+    #
+    # @param code [String] The short link code
+    # @param disabled [Boolean] true to disable, false to re-enable
+    # @return [Sendly::ShortLinkStatus] The link's code and new disabled state
+    #
+    # @raise [Sendly::NotFoundError] If no such link exists in your workspace
+    def update(code, disabled:)
+      raise ValidationError, "Link code is required" if code.nil? || code.to_s.empty?
+
+      encoded_code = URI.encode_www_form_component(code)
+      response = @client.patch("/links/#{encoded_code}", { disabled: disabled })
+      ShortLinkStatus.new(response)
+    end
+
+    # Disable a short link (its redirect returns 404 until re-enabled).
+    # Convenience wrapper over {#update}.
+    #
+    # @param code [String] The short link code
+    # @return [Sendly::ShortLinkStatus]
+    def disable(code)
+      update(code, disabled: true)
+    end
+
+    # Re-enable a previously disabled short link. Convenience wrapper over
+    # {#update}.
+    #
+    # @param code [String] The short link code
+    # @return [Sendly::ShortLinkStatus]
+    def enable(code)
+      update(code, disabled: false)
+    end
+
+    private
+
+    # Client-side guard mirroring the server's http/https-only check.
+    def validate_url!(url)
+      raise ValidationError, "url is required" if url.nil? || url.to_s.empty?
+
+      return if url.is_a?(String) && (url.start_with?("http://") || url.start_with?("https://"))
+
+      raise ValidationError, "url must be an http:// or https:// URL"
+    end
+  end
+end

data/lib/sendly/messages.rb

@@ -14,6 +14,7 @@ module Sendly
     #
     # @param to [String] Recipient phone number in E.164 format
     # @param text [String] Message content (max 1600 characters)
+    # @param from [String] Sender ID or phone number (optional)
     # @param message_type [String] Message type: "marketing" (default) or "transactional"
     # @param metadata [Hash] Custom JSON metadata to attach to the message (max 4KB)
     # @return [Sendly::Message] The sent message
@@ -36,11 +37,12 @@ module Sendly
     #     text: "Your verification code is 123456",
     #     message_type: "transactional"
     #   )
-    def send(to:, text:, message_type: nil, metadata: nil, media_urls: nil)
+    def send(to:, text:, from: nil, message_type: nil, metadata: nil, media_urls: nil)
       validate_phone!(to)
       validate_text!(text)
 
       body = { to: to, text: text }
+      body[:from] = from if from
       body[:messageType] = message_type if message_type
       body[:metadata] = metadata if metadata
       body[:mediaUrls] = media_urls if media_urls
@@ -50,6 +52,89 @@ module Sendly
       Message.new(response)
     end
 
+    # Send a group MMS to 2-8 recipients (US/Canada only)
+    #
+    # Creates a multi-party MMS conversation: every recipient sees the others,
+    # and replies fan out to all participants. Group messaging is an A2P 10DLC
+    # capability — the sending number must be an MMS-enabled, 10DLC-registered
+    # number you own. Omit +from+ to use your workspace's default sender.
+    # Requires the +group_mms+ feature (and +enable_mms+ when sending media).
+    #
+    # @param to [Array<String>] 2-8 recipient phone numbers in E.164 format (US/CA only)
+    # @param text [String] Message content (required unless media_urls is provided)
+    # @param from [String] Sender ID or phone number (optional)
+    # @param media_urls [Array<String>] Media URLs to attach (required unless text is provided)
+    # @param message_type [String] Message type: "transactional" (default) or "marketing"
+    # @return [Sendly::GroupMessage] The sent group message, including a group_message_id
+    #
+    # @raise [Sendly::ValidationError] If fewer than 2 / more than 8 recipients, or no body
+    # @raise [Sendly::InsufficientCreditsError] If credit balance is too low (billed per recipient)
+    #
+    # @example
+    #   group = client.messages.send_group(
+    #     to: ["+14155551234", "+14155555678"],
+    #     text: "Hey team - quick sync at noon?"
+    #   )
+    #   puts group.id
+    #   puts group.group_message_id
+    def send_group(to:, text: nil, from: nil, media_urls: nil, message_type: nil)
+      unless to.is_a?(Array) && to.length >= 2
+        raise ValidationError, "Group messaging requires at least 2 recipients in 'to'"
+      end
+      raise ValidationError, "Group messaging supports at most 8 recipients" if to.length > 8
+
+      to.each { |recipient| validate_phone!(recipient) }
+
+      has_media = media_urls.is_a?(Array) && !media_urls.empty?
+      raise ValidationError, "Provide 'text' or 'media_urls'" if (text.nil? || text.empty?) && !has_media
+
+      body = { to: to }
+      body[:text] = text if text && !text.empty?
+      body[:from] = from if from
+      body[:mediaUrls] = media_urls if has_media
+      body[:messageType] = message_type if message_type
+
+      response = client.post("/messages/group", body)
+      GroupMessage.new(response)
+    end
+
+    # AI-enhance a draft message for clarity, compliance, and send-readiness
+    #
+    # Rewrites the supplied text into a single, polished SMS segment (<=160
+    # chars) and returns a short explanation of what changed. Pass +message_type+
+    # to steer the rewrite (e.g. "marketing" vs "transactional"); with no +text+
+    # it generates a suitable message for that type instead. At least one of
+    # +text+ or +message_type+ is required. Requires the +ai_classification+
+    # feature. When AI enhancement is unavailable, the response falls back to the
+    # original text with an empty explanation.
+    #
+    # @param text [String] Draft message text to rewrite (optional if message_type given)
+    # @param message_type [String] Message-type hint, e.g. "marketing" or "transactional"
+    # @return [Sendly::EnhancedMessage] The enhanced text, an explanation, and the model used
+    #
+    # @raise [Sendly::ValidationError] If neither text nor message_type is provided
+    # @raise [Sendly::NotFoundError] If AI enhancement is not enabled for the account
+    #
+    # @example
+    #   result = client.messages.enhance(
+    #     text: "hey come check out our sale this weekend",
+    #     message_type: "marketing"
+    #   )
+    #   puts result.enhanced     # polished, <=160-char rewrite
+    #   puts result.explanation  # what changed and why
+    def enhance(text: nil, message_type: nil)
+      if (text.nil? || text.to_s.empty?) && (message_type.nil? || message_type.to_s.empty?)
+        raise ValidationError, "Provide 'text' or 'message_type'"
+      end
+
+      body = {}
+      body[:text] = text unless text.nil?
+      body[:messageType] = message_type if message_type
+
+      response = client.post("/ai/enhance", body)
+      EnhancedMessage.new(response)
+    end
+
     # List messages
     #
     # @param limit [Integer] Maximum messages to return (default: 20, max: 100)

data/lib/sendly/numbers_resource.rb

@@ -42,7 +42,18 @@ module Sendly
   # A number owned by the account.
   class PhoneNumber
     attr_reader :id, :phone_number, :status, :source, :country_code,
-                :phone_number_type, :monthly_cost_cents
+                :phone_number_type, :monthly_cost_cents,
+                # true when this is the workspace's default sender. Only present
+                # on single-number responses ({NumbersResource#get} /
+                # {NumbersResource#update}); nil in the {NumbersResource#list} projection.
+                :is_default,
+                # ISO-8601 timestamp string, or nil when the number still needs
+                # regulatory documents (a value means docs are under carrier review).
+                :requirements_submitted_at,
+                # true when the number is scheduled for release at period end.
+                :pending_cancellation,
+                # ISO-8601 timestamp string, or nil when no release is scheduled.
+                :scheduled_release_at
 
     def initialize(data)
       @id = data["id"]
@@ -52,13 +63,20 @@ module Sendly
       @country_code = data["countryCode"] || data["country_code"]
       @phone_number_type = data["phoneNumberType"] || data["phone_number_type"]
       @monthly_cost_cents = data["monthlyCostCents"] || data["monthly_cost_cents"]
+      @is_default = data.key?("isDefault") ? data["isDefault"] : data["is_default"]
+      @requirements_submitted_at = data["requirementsSubmittedAt"] || data["requirements_submitted_at"]
+      @pending_cancellation = data.key?("pendingCancellation") ? data["pendingCancellation"] : data["pending_cancellation"]
+      @scheduled_release_at = data["scheduledReleaseAt"] || data["scheduled_release_at"]
     end
 
     def to_h
       {
         id: id, phone_number: phone_number, status: status, source: source,
         country_code: country_code, phone_number_type: phone_number_type,
-        monthly_cost_cents: monthly_cost_cents
+        monthly_cost_cents: monthly_cost_cents, is_default: is_default,
+        requirements_submitted_at: requirements_submitted_at,
+        pending_cancellation: pending_cancellation,
+        scheduled_release_at: scheduled_release_at
       }.compact
     end
   end
@@ -147,6 +165,45 @@ module Sendly
     end
   end
 
+  # The result of releasing an owned number via {NumbersResource#release}.
+  #
+  # A live paid purchase is cancelled at the end of the paid period — the result
+  # then reports +scheduled?+ true with a +scheduled_release_at+ timestamp.
+  # Everything else is released immediately (+scheduled?+ false, no timestamp).
+  # The raw parsed response is preserved on +#raw+.
+  class NumberRelease
+    # @return [Boolean] true on success
+    attr_reader :success
+
+    # @return [Boolean] true when the release was scheduled for the period end
+    attr_reader :scheduled
+
+    # @return [String, nil] ISO-8601 timestamp the scheduled release takes effect
+    attr_reader :scheduled_release_at
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    def initialize(data)
+      @raw = data
+      @success = data.key?("success") ? data["success"] : true
+      @scheduled = data["scheduled"] || false
+      @scheduled_release_at = data["scheduledReleaseAt"] || data["scheduled_release_at"]
+    end
+
+    # @return [Boolean] Whether the release was scheduled (vs immediate)
+    def scheduled?
+      scheduled
+    end
+
+    def to_h
+      {
+        success: success, scheduled: scheduled,
+        scheduled_release_at: scheduled_release_at
+      }.compact
+    end
+  end
+
   # Numbers resource — search, list, and purchase phone numbers.
   #
   # @example List supported countries
@@ -244,5 +301,67 @@ module Sendly
       response = @client.post("/numbers/buy", body)
       NumberPurchase.new(response)
     end
+
+    # Get a single number owned by the account.
+    #
+    # Unlike the entries {#list} returns, this includes +is_default+ — whether
+    # the number is the workspace's default sender.
+    #
+    # @param id [String] The number's id
+    # @return [PhoneNumber]
+    # @raise [Sendly::NotFoundError] If no such number exists in your workspace
+    def get(id)
+      raise ValidationError, "id is required" if id.nil? || id.to_s.empty?
+
+      encoded_id = URI.encode_www_form_component(id)
+      response = @client.get("/numbers/#{encoded_id}")
+      PhoneNumber.new(response)
+    end
+
+    # Update a number you own. Supply at least one supported mutation — these are
+    # the only two the API supports:
+    #
+    # - +is_default: true+ — make this the workspace's default sending number
+    #   (the number must be +active+).
+    # - +pending_cancellation: false+ — cancel a previously scheduled release and
+    #   keep the number.
+    #
+    # @param id [String] The number's id
+    # @param is_default [Boolean, nil] Pass +true+ to make this the default sender
+    # @param pending_cancellation [Boolean, nil] Pass +false+ to cancel a scheduled release
+    # @return [PhoneNumber] The updated number (including +is_default+)
+    # @raise [Sendly::ValidationError] If no supported field is given, or +is_default+
+    #   is requested for a non-active number
+    # @raise [Sendly::NotFoundError] If no such number exists in your workspace
+    def update(id, is_default: nil, pending_cancellation: nil)
+      raise ValidationError, "id is required" if id.nil? || id.to_s.empty?
+      if is_default.nil? && pending_cancellation.nil?
+        raise ValidationError, "Provide is_default: true and/or pending_cancellation: false"
+      end
+
+      body = {}
+      body[:isDefault] = is_default unless is_default.nil?
+      body[:pendingCancellation] = pending_cancellation unless pending_cancellation.nil?
+
+      encoded_id = URI.encode_www_form_component(id)
+      response = @client.patch("/numbers/#{encoded_id}", body)
+      PhoneNumber.new(response)
+    end
+
+    # Release a number you own. A live paid purchase is cancelled at the end of
+    # the paid period (the result then reports +scheduled?+ true with a
+    # +scheduled_release_at+); everything else is released immediately.
+    #
+    # @param id [String] The number's id
+    # @return [NumberRelease]
+    # @raise [Sendly::NotFoundError] If no such number exists in your workspace
+    # @raise [Sendly::ValidationError] If the carrier release failed
+    def release(id)
+      raise ValidationError, "id is required" if id.nil? || id.to_s.empty?
+
+      encoded_id = URI.encode_www_form_component(id)
+      response = @client.delete("/numbers/#{encoded_id}")
+      NumberRelease.new(response)
+    end
   end
 end