kit-rb 0.1.0 → 0.3.0

data/lib/kit/errors.rb

@@ -8,24 +8,51 @@ module Kit
   # (e.g. no credentials supplied).
   class ConfigurationError < Error; end
 
+  # Base for failures below HTTP: the request never got a response. `cause`
+  # is the underlying http.rb exception.
+  class TransportError < Error; end
+  # The connection or read timed out (config.open_timeout / read_timeout).
+  class TimeoutError < TransportError; end
+  # The connection could not be established or was dropped (DNS, refused,
+  # reset, TLS).
+  class ConnectionError < TransportError; end
+
+  # Raised when a 2xx response does not have the shape the resource expects
+  # (a missing envelope key, a non-JSON body). Distinct from APIError because
+  # the request succeeded; the client and the API disagree about the payload.
+  # `body` is the parsed (or raw) response body for diagnosis.
+  class UnexpectedResponseError < Error
+    attr_reader :body
+
+    def initialize(message, body: nil)
+      @body = body
+      super(message)
+    end
+  end
+
   # Base for every error that carries an HTTP response. `status` is the code,
   # `body` the parsed JSON body (or the raw string when it wasn't JSON), and
-  # `errors` the `errors` array Kit returns on validation failures.
+  # `errors` the `errors` array Kit returns on validation failures. `method`
+  # and `path` identify the request that failed (nil for OAuth token errors).
   class APIError < Error
-    attr_reader :status, :body, :errors, :response
+    attr_reader :status, :body, :errors, :response, :method, :path
 
-    def initialize(message = nil, status:, body: nil, response: nil)
+    def initialize(message = nil, status:, body: nil, response: nil, method: nil, path: nil)
       @status = status
       @body = body
       @response = response
+      @method = method
+      @path = path
       @errors = body.is_a?(Hash) ? Array(body["errors"]) : []
       super(message || default_message)
     end
 
     private
 
+    # e.g. "GET /v4/subscribers/1 failed with status 404: Not Found"
     def default_message
-      base = "Kit API request failed with status #{status}"
+      request = method && path ? "#{method.to_s.upcase} #{path}" : "Kit API request"
+      base = "#{request} failed with status #{status}"
       @errors.empty? ? base : "#{base}: #{@errors.join(", ")}"
     end
   end
@@ -36,6 +63,12 @@ module Kit
   class AuthorizationError < APIError; end
   # 404 — no such resource.
   class NotFoundError < APIError; end
+  # 409 — the request conflicts with current state (e.g. rotating a webhook
+  # endpoint secret while a previous rotation is still in its grace period).
+  class ConflictError < APIError; end
+  # 413 — the request exceeds Kit's size quota (the bulk endpoints' enqueued
+  # data cap); split the batch.
+  class PayloadTooLargeError < APIError; end
   # 422 — the request was well-formed but semantically invalid.
   class UnprocessableEntityError < APIError; end
 
@@ -43,9 +76,9 @@ module Kit
   class RateLimitError < APIError
     attr_reader :retry_after
 
-    def initialize(message = nil, status:, body: nil, response: nil, retry_after: nil)
+    def initialize(message = nil, status:, body: nil, response: nil, method: nil, path: nil, retry_after: nil)
       @retry_after = retry_after
-      super(message, status: status, body: body, response: response)
+      super(message, status: status, body: body, response: response, method: method, path: path)
     end
   end
 
@@ -69,16 +102,20 @@ module Kit
 
   # Maps an HTTP status to the most specific error class above.
   class Error
+    STATUS_CLASSES = {
+      401 => AuthenticationError,
+      403 => AuthorizationError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      413 => PayloadTooLargeError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError
+    }.freeze
+
     def self.class_for(status)
-      case status
-      when 401 then AuthenticationError
-      when 403 then AuthorizationError
-      when 404 then NotFoundError
-      when 422 then UnprocessableEntityError
-      when 429 then RateLimitError
-      when 500..599 then ServerError
-      else APIError
-      end
+      return ServerError if (500..599).cover?(status)
+
+      STATUS_CLASSES.fetch(status, APIError)
     end
   end
 end

data/lib/kit/oauth/token.rb

@@ -19,6 +19,15 @@ module Kit
         )
       end
 
+      # Both tokens are masked in #inspect; #to_h still returns the real values
+      # for persistence.
+      def inspect
+        "#<data #{self.class.name} access_token=#{Auth::Credential.mask(access_token)}, " \
+          "refresh_token=#{Auth::Credential.mask(refresh_token)}, token_type=#{token_type.inspect}, " \
+          "expires_in=#{expires_in.inspect}, scope=#{scope.inspect}, created_at=#{created_at.inspect}>"
+      end
+      alias_method :to_s, :inspect
+
       # Unix time the access token expires, or nil when the fields are absent.
       def expires_at
         return nil unless created_at && expires_in

data/lib/kit/objects/account.rb

@@ -9,16 +9,57 @@ module Kit
       end
     end
 
+    # The account's timezone, nested under account.timezone.
+    Timezone = Data.define(:name, :friendly_name, :utc_offset) do
+      def self.from(hash)
+        new(name: hash["name"], friendly_name: hash["friendly_name"], utc_offset: hash["utc_offset"])
+      end
+    end
+
+    # Billing plan details, nested under account.plan.
+    Plan = Data.define(
+      :plan_type, :interval, :subscriber_limit, :on_trial, :trial_lapse_date, :renews_at, :cancels_at
+    ) do
+      def self.from(hash)
+        new(
+          plan_type: hash["plan_type"], interval: hash["interval"], subscriber_limit: hash["subscriber_limit"],
+          on_trial: hash["on_trial"], trial_lapse_date: hash["trial_lapse_date"],
+          renews_at: hash["renews_at"], cancels_at: hash["cancels_at"]
+        )
+      end
+    end
+
+    # One verified sender address, listed under account.sending_addresses.
+    SendingAddress = Data.define(
+      :email_address, :from_name, :status, :is_default, :is_verified, :is_dmarc_configured
+    ) do
+      def self.from(hash)
+        new(
+          email_address: hash["email_address"], from_name: hash["from_name"], status: hash["status"],
+          is_default: hash["is_default"], is_verified: hash["is_verified"],
+          is_dmarc_configured: hash["is_dmarc_configured"]
+        )
+      end
+    end
+
     # The account half of GET /v4/account. Extra fields Kit adds later are
-    # ignored rather than crashing the client (forward-compatible).
-    Account = Data.define(:id, :name, :plan_type, :primary_email_address, :created_at) do
+    # ignored rather than crashing the client (forward-compatible). `timezone`
+    # and `plan` are typed sub-objects (nil when absent); `sending_addresses` is
+    # an Array of SendingAddress.
+    Account = Data.define(
+      :id, :name, :plan_type, :primary_email_address, :created_at,
+      :timezone, :plan, :sending_addresses
+    ) do
       def self.from(hash)
         new(
           id: hash["id"],
           name: hash["name"],
           plan_type: hash["plan_type"],
           primary_email_address: hash["primary_email_address"],
-          created_at: hash["created_at"]
+          created_at: hash["created_at"],
+          timezone: hash["timezone"] && Timezone.from(hash["timezone"]),
+          plan: hash["plan"] && Plan.from(hash["plan"]),
+          sending_addresses: Array(hash["sending_addresses"]).map { |address| SendingAddress.from(address) }
         )
       end
     end

data/lib/kit/objects/broadcast_click.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # One clicked link in a broadcast's click report
+    # (/v4/broadcasts/:id/clicks), with its click totals and rates.
+    BroadcastClick = Data.define(
+      :id, :url, :unique_clicks, :click_to_delivery_rate, :click_to_open_rate
+    ) do
+      def self.from(hash)
+        new(id: hash["id"], url: hash["url"], unique_clicks: hash["unique_clicks"],
+            click_to_delivery_rate: hash["click_to_delivery_rate"],
+            click_to_open_rate: hash["click_to_open_rate"])
+      end
+    end
+  end
+end

data/lib/kit/objects/broadcast_stats.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # Performance stats for a broadcast, as returned by /v4/broadcasts/:id/stats
+    # and each row of /v4/broadcasts/stats. The API nests the metrics under a
+    # "stats" key alongside id/subject/send_at; this flattens them into one
+    # object (subject/send_at are absent on the single-broadcast endpoint).
+    BroadcastStats = Data.define(
+      :id, :subject, :send_at, :recipients, :open_rate, :emails_opened,
+      :click_rate, :unsubscribe_rate, :unsubscribes, :total_clicks,
+      :show_total_clicks, :status, :progress, :open_tracking_disabled,
+      :click_tracking_disabled
+    ) do
+      def self.from(hash)
+        stats = hash["stats"] || {}
+        new(
+          id: hash["id"], subject: hash["subject"], send_at: hash["send_at"],
+          recipients: stats["recipients"], open_rate: stats["open_rate"],
+          emails_opened: stats["emails_opened"], click_rate: stats["click_rate"],
+          unsubscribe_rate: stats["unsubscribe_rate"], unsubscribes: stats["unsubscribes"],
+          total_clicks: stats["total_clicks"], show_total_clicks: stats["show_total_clicks"],
+          status: stats["status"], progress: stats["progress"],
+          open_tracking_disabled: stats["open_tracking_disabled"],
+          click_tracking_disabled: stats["click_tracking_disabled"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/bulk_result.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # One rejected item from a bulk call: `item` is the input echoed back by
+    # Kit (the hash under "subscriber"/"tag"/... — the key varies per
+    # endpoint) and `errors` the validation messages for it.
+    BulkFailure = Data.define(:item, :errors) do
+      def self.from(hash)
+        new(item: hash.except("errors").values.first,
+            errors: Array(hash["errors"]))
+      end
+    end
+
+    # The outcome of a /v4/bulk call. Small batches are applied synchronously
+    # (200): `items` are the created/affected records as raw Hashes — their
+    # shape is endpoint-specific and partial — and `failures` the rejected
+    # inputs. Batches over Kit's inline threshold are queued (202, empty
+    # body): `async?` is true, `items`/`failures` are empty, and the full
+    # result is POSTed to the request's callback_url when processing ends.
+    BulkResult = Data.define(:items, :failures, :async) do
+      # `key` is the envelope key of the affected records ("subscribers",
+      # "tags", ...), or nil for the delete endpoints, which return failures only.
+      def self.from(status, body, key)
+        body = {} unless body.is_a?(Hash)
+        new(
+          items: key ? Array(body[key]) : [],
+          failures: Array(body["failures"]).map { |failure| BulkFailure.from(failure) },
+          async: status == 202
+        )
+      end
+
+      def async? = async
+
+      # True when Kit applied the batch now and rejected nothing.
+      def success? = !async && failures.empty?
+    end
+  end
+end

data/lib/kit/objects/custom_field.rb

@@ -5,9 +5,11 @@ module Kit
     # A custom field as returned by /v4/custom_fields. `label` is what a creator
     # sets; `key` is the derived attribute used on subscribers (e.g. a `label`
     # of "Last name" yields a `key` of "last_name").
-    CustomField = Data.define(:id, :name, :key, :label) do
+    # `created_at` is returned by the bulk create endpoint only.
+    CustomField = Data.define(:id, :name, :key, :label, :created_at) do
       def self.from(hash)
-        new(id: hash["id"], name: hash["name"], key: hash["key"], label: hash["label"])
+        new(id: hash["id"], name: hash["name"], key: hash["key"], label: hash["label"],
+            created_at: hash["created_at"])
       end
     end
   end

data/lib/kit/objects/email_stats.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # Account-wide email engagement stats (/v4/account/email_stats), covering the
+    # window [starting, ending].
+    EmailStats = Data.define(
+      :sent, :clicked, :opened, :email_stats_mode,
+      :open_tracking_enabled, :click_tracking_enabled,
+      :starting, :ending, :open_rate, :click_rate, :unsubscribe_rate, :bounce_rate
+    ) do
+      def self.from(hash)
+        new(
+          sent: hash["sent"], clicked: hash["clicked"], opened: hash["opened"],
+          email_stats_mode: hash["email_stats_mode"],
+          open_tracking_enabled: hash["open_tracking_enabled"],
+          click_tracking_enabled: hash["click_tracking_enabled"],
+          starting: hash["starting"], ending: hash["ending"],
+          open_rate: hash["open_rate"], click_rate: hash["click_rate"],
+          unsubscribe_rate: hash["unsubscribe_rate"], bounce_rate: hash["bounce_rate"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/growth_stats.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # Account subscriber-growth stats (/v4/account/growth_stats) over the window
+    # [starting, ending].
+    GrowthStats = Data.define(
+      :cancellations, :net_new_subscribers, :new_subscribers, :subscribers,
+      :starting, :ending
+    ) do
+      def self.from(hash)
+        new(
+          cancellations: hash["cancellations"], net_new_subscribers: hash["net_new_subscribers"],
+          new_subscribers: hash["new_subscribers"], subscribers: hash["subscribers"],
+          starting: hash["starting"], ending: hash["ending"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/post.rb

@@ -4,10 +4,12 @@ module Kit
   module Objects
     # A post (a broadcast published to the web) as returned by /v4/posts.
     # `publication_id` ties it back to the broadcast it was published from.
+    # `content` (the HTML body) is present on a single-post read and on list
+    # reads made with include_content: true; nil otherwise.
     Post = Data.define(
       :id, :publication_id, :created_at, :title, :slug, :description,
       :meta_description, :status, :published_at, :sent_at,
-      :thumbnail_alt, :thumbnail_url, :is_paid, :public_url
+      :thumbnail_alt, :thumbnail_url, :is_paid, :public_url, :content
     ) do
       def self.from(hash)
         new(
@@ -16,7 +18,7 @@ module Kit
           meta_description: hash["meta_description"], status: hash["status"],
           published_at: hash["published_at"], sent_at: hash["sent_at"],
           thumbnail_alt: hash["thumbnail_alt"], thumbnail_url: hash["thumbnail_url"],
-          is_paid: hash["is_paid"], public_url: hash["public_url"]
+          is_paid: hash["is_paid"], public_url: hash["public_url"], content: hash["content"]
         )
       end
     end

data/lib/kit/objects/sequence_email.rb

@@ -5,9 +5,11 @@ module Kit
     # An email within a sequence, as returned by
     # /v4/sequences/:sequence_id/emails. `position` is its order in the sequence;
     # `delay_value`/`delay_unit` set how long after the previous step it sends.
+    # `content` (the HTML body) is present on a single-email read, on
+    # create/update responses, and on list reads with include_content: true.
     SequenceEmail = Data.define(
       :id, :sequence_id, :subject, :preview_text, :email_address, :email_template_id,
-      :published, :position, :delay_value, :delay_unit, :send_days, :stats
+      :published, :position, :delay_value, :delay_unit, :send_days, :content, :stats
     ) do
       def self.from(hash)
         new(
@@ -15,7 +17,8 @@ module Kit
           preview_text: hash["preview_text"], email_address: hash["email_address"],
           email_template_id: hash["email_template_id"], published: hash["published"],
           position: hash["position"], delay_value: hash["delay_value"],
-          delay_unit: hash["delay_unit"], send_days: hash["send_days"], stats: hash["stats"]
+          delay_unit: hash["delay_unit"], send_days: hash["send_days"], content: hash["content"],
+          stats: hash["stats"]
         )
       end
     end

data/lib/kit/objects/subscriber.rb

@@ -4,20 +4,27 @@ module Kit
   module Objects
     # A subscriber as returned by /v4/subscribers. `fields` holds custom-field
     # values; `location` is present on some responses; both are plain Hashes.
+    #
+    # Context fields, nil unless the endpoint supplies them:
+    # - `added_at`, `referrer`, `referrer_utm_parameters` — form/sequence
+    #   subscriber lists (when this subscriber joined through that form/sequence)
+    # - `tagged_at` — a tag's subscriber list
+    # - `attribution`, `tags` — list reads made with include: "attribution,tags"
+    # - `tag_names`, `tag_ids`, `stats` — POST /v4/subscribers/filter
     Subscriber = Data.define(
       :id, :first_name, :email_address, :state,
-      :created_at, :canceled_at, :location, :fields
+      :created_at, :canceled_at, :location, :fields,
+      :added_at, :tagged_at, :referrer, :referrer_utm_parameters,
+      :attribution, :tags, :tag_names, :tag_ids, :stats
     ) do
       def self.from(hash)
         new(
-          id: hash["id"],
-          first_name: hash["first_name"],
-          email_address: hash["email_address"],
-          state: hash["state"],
-          created_at: hash["created_at"],
-          canceled_at: hash["canceled_at"],
-          location: hash["location"],
-          fields: hash["fields"]
+          id: hash["id"], first_name: hash["first_name"], email_address: hash["email_address"],
+          state: hash["state"], created_at: hash["created_at"], canceled_at: hash["canceled_at"],
+          location: hash["location"], fields: hash["fields"],
+          added_at: hash["added_at"], tagged_at: hash["tagged_at"], referrer: hash["referrer"],
+          referrer_utm_parameters: hash["referrer_utm_parameters"], attribution: hash["attribution"],
+          tags: hash["tags"], tag_names: hash["tag_names"], tag_ids: hash["tag_ids"], stats: hash["stats"]
         )
       end
     end

data/lib/kit/objects/subscriber_stats.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # Engagement stats for a subscriber (/v4/subscribers/:id/stats). The API
+    # nests the metrics under "stats" next to the id; this flattens them.
+    SubscriberStats = Data.define(
+      :id, :sent, :opened, :clicked, :bounced, :open_rate, :click_rate,
+      :last_sent, :last_opened, :last_clicked,
+      :sends_since_last_open, :sends_since_last_click
+    ) do
+      def self.from(hash)
+        stats = hash["stats"] || {}
+        new(
+          id: hash["id"], sent: stats["sent"], opened: stats["opened"],
+          clicked: stats["clicked"], bounced: stats["bounced"],
+          open_rate: stats["open_rate"], click_rate: stats["click_rate"],
+          last_sent: stats["last_sent"], last_opened: stats["last_opened"],
+          last_clicked: stats["last_clicked"],
+          sends_since_last_open: stats["sends_since_last_open"],
+          sends_since_last_click: stats["sends_since_last_click"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/tag.rb

@@ -2,14 +2,16 @@
 
 module Kit
   module Objects
-    # A tag as returned by /v4/tags. Fields are all non-nil.
-    Tag = Data.define(:id, :name, :created_at, :subscriber_count) do
+    # A tag as returned by /v4/tags. `tagged_at` is set only when the tag is
+    # read through a subscriber (/v4/subscribers/:id/tags): when it was applied.
+    Tag = Data.define(:id, :name, :created_at, :subscriber_count, :tagged_at) do
       def self.from(hash)
         new(
           id: hash["id"],
           name: hash["name"],
           created_at: hash["created_at"],
-          subscriber_count: hash["subscriber_count"]
+          subscriber_count: hash["subscriber_count"],
+          tagged_at: hash["tagged_at"]
         )
       end
     end

data/lib/kit/objects/webhook_endpoint.rb

@@ -5,16 +5,21 @@ module Kit
     # A webhook endpoint as returned by /v4/webhook_endpoints — the newer signed-
     # delivery model, with a secret that can be rotated. `events` is the list of
     # subscribed event names; `previous_secret_expires_at` is set after a rotate.
+    #
+    # `secret` (the `whsec_`-prefixed signing secret) is present only on the
+    # response to `create` and `rotate_secret` — Kit never returns it again, so
+    # persist it from that object. It is nil on every other read.
     WebhookEndpoint = Data.define(
       :id, :name, :url, :events, :status, :source, :description,
-      :created_by_app, :created_at, :previous_secret_expires_at
+      :created_by_app, :created_at, :previous_secret_expires_at, :secret
     ) do
       def self.from(hash)
         new(
           id: hash["id"], name: hash["name"], url: hash["url"], events: hash["events"],
           status: hash["status"], source: hash["source"], description: hash["description"],
           created_by_app: hash["created_by_app"], created_at: hash["created_at"],
-          previous_secret_expires_at: hash["previous_secret_expires_at"]
+          previous_secret_expires_at: hash["previous_secret_expires_at"],
+          secret: hash["secret"]
         )
       end
     end

data/lib/kit/pagination.rb

@@ -3,17 +3,24 @@
 module Kit
   # The `pagination` object Kit returns alongside every list. Kit uses cursor
   # pagination: to walk forward, pass `after: end_cursor`; backward, `before:
-  # start_cursor`.
+  # start_cursor`. `total_count` is present only when the request asked for it
+  # with `include_total_count: true` (nil otherwise).
   Pagination = Data.define(
-    :has_previous_page, :has_next_page, :start_cursor, :end_cursor, :per_page
+    :has_previous_page, :has_next_page, :start_cursor, :end_cursor, :per_page, :total_count
   ) do
+    # total_count is optional so Pagination.new(...) without it keeps working.
+    def initialize(total_count: nil, **rest)
+      super
+    end
+
     def self.from(hash)
       new(
         has_previous_page: hash["has_previous_page"],
         has_next_page: hash["has_next_page"],
         start_cursor: hash["start_cursor"],
         end_cursor: hash["end_cursor"],
-        per_page: hash["per_page"]
+        per_page: hash["per_page"],
+        total_count: hash["total_count"]
       )
     end
   end
@@ -29,8 +36,23 @@ module Kit
   class Collection
     include Enumerable
 
+    # Query params that must not be carried into a follow-up page request: a
+    # `before` cursor contradicts the `after` we add, and Kit asks that
+    # `include_total_count` be sent on the first page only.
+    FIRST_PAGE_ONLY = %i[before include_total_count].freeze
+
+    # The params for the page after `after`, derived from the original request.
+    def self.next_page_params(params, after)
+      params.reject { |key, _| FIRST_PAGE_ONLY.include?(key.to_sym) }.merge(after: after)
+    end
+
     attr_reader :data, :pagination
 
+    # Kit's total across all pages, when the first request asked for it.
+    def total_count
+      @pagination.total_count
+    end
+
     def initialize(data:, pagination:, &fetch_after)
       @data = data
       @pagination = pagination
@@ -42,6 +64,28 @@ module Kit
       @data.each(&)
     end
 
+    # Size of the current page (not the total across pages — see total_count).
+    def size
+      @data.size
+    end
+    alias length size
+
+    def empty?
+      @data.empty?
+    end
+
+    # Positional access into the current page.
+    def [](index)
+      @data[index]
+    end
+
+    # e.g. #<Kit::Collection[Kit::Objects::Tag] size=2 has_next_page=true total_count=57>
+    def inspect
+      element = @data.first&.class&.name
+      "#<#{self.class.name}#{"[#{element}]" if element} size=#{size} " \
+        "has_next_page=#{@pagination.has_next_page.inspect} total_count=#{total_count.inspect}>"
+    end
+
     # The next Collection, or nil when there is no next page.
     def next_page
       return nil unless @pagination.has_next_page

data/lib/kit/resources/account.rb

@@ -2,8 +2,8 @@
 
 module Kit
   module Resources
-    # The /v4/account endpoints. P0 covers the current-account read; colors,
-    # creator_profile, email_stats, and growth_stats follow in P1/P2.
+    # The /v4/account endpoints: the current account, its colour palette,
+    # creator profile, and account-wide email and growth stats.
     class Account < Base
       # GET /v4/account — current account and user info.
       #
@@ -14,12 +14,12 @@ module Kit
 
       # GET /v4/account/colors — the account's brand color palette (hex strings).
       def colors
-        http_get("/v4/account/colors").fetch("colors")
+        extract(http_get("/v4/account/colors"), "colors")
       end
 
       # PUT /v4/account/colors — replace the palette; returns the saved colors.
       def update_colors(colors)
-        http_put("/v4/account/colors", body: { colors: colors }).fetch("colors")
+        extract(http_put("/v4/account/colors", body: { colors: colors }), "colors")
       end
 
       # GET /v4/account/creator_profile
@@ -27,14 +27,15 @@ module Kit
         one(:get, "/v4/account/creator_profile", "profile", Objects::CreatorProfile)
       end
 
-      # GET /v4/account/email_stats — returns the raw stats hash.
+      # GET /v4/account/email_stats — account-wide email engagement stats.
       def email_stats
-        http_get("/v4/account/email_stats").fetch("stats")
+        one(:get, "/v4/account/email_stats", "stats", Objects::EmailStats)
       end
 
-      # GET /v4/account/growth_stats — raw stats hash; accepts starting/ending.
+      # GET /v4/account/growth_stats — subscriber-growth stats; accepts
+      # starting/ending to bound the window.
       def growth_stats(**params)
-        http_get("/v4/account/growth_stats", params: params).fetch("stats")
+        one(:get, "/v4/account/growth_stats", "stats", Objects::GrowthStats, params: params)
       end
     end
   end