kit-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa9f06f61a89d938cb719fcbd0cad578e8dd6d6ffc35fcf9b17d356f6a9160b3
-  data.tar.gz: 6279b4801b2cd8738b11bcc43babad6b8654739683ace8ff86389e040b8a994b
+  metadata.gz: 5c627d63853645447ea42de84d81c8e30141478644e74c844a318af8962e53d2
+  data.tar.gz: 1c54a33e809f7d1e66a2342ed361551e8ec6c365e991bd56b1b6e93c5c2a06bd
 SHA512:
-  metadata.gz: 3cc4008cae00b1fe78391e5816b3e19040103c86b5d4feedbc8a03fdce856325e969840f4d568c583f2f5a1bd579f69ffd403c7e515cfca611a3ea0eca24b636
-  data.tar.gz: 279c04700c82548a16c64637d72269d1ad36a06419228e5ba738e603f98f23983f60183078a79c5a166dee45bc40d5f36a50c4b841a969d020acdaa6bdebf8b7
+  metadata.gz: 455b8b55b3a263194e59c7567f9ec46e8388eaed94db902f13fdd213e19a2898b3a4d7657adf8862c6edfa8bfdcc32680b395dac4a1edd09cbc3741f9a40e565
+  data.tar.gz: 96f26f83e33a0a6d95b573d59a29afd78cb612eef9a6ccba76c5e355f5cb3b6693345c245646fd27d5bb9aeb720ef264f99c5bc9fcd6cea4bdcfa00d5bbc6c44

data/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-09-04
+
+### Changed
+- **Breaking:** the stats and analytics endpoints now return typed value objects
+  instead of raw hashes, matching every other resource:
+  `broadcasts.stats`/`stats_list` → `Objects::BroadcastStats` (the nested metrics
+  flattened), `broadcasts.clicks` → `Collection[Objects::BroadcastClick]`,
+  `subscribers.stats` → `Objects::SubscriberStats`, `account.email_stats` →
+  `Objects::EmailStats`, and `account.growth_stats` → `Objects::GrowthStats`.
+
+### Removed
+- `Objects::Raw` (the identity used by the old raw-hash stats returns).
+
 ## [0.1.0] - 2026-09-04
 
 First feature-complete release: the entire Kit API v4 surface — all 81 documented

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/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/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/resources/account.rb

@@ -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

data/lib/kit/resources/broadcasts.rb

@@ -31,21 +31,25 @@ module Kit
         nil
       end
 
-      # GET /v4/broadcasts/stats — a cursor-paginated list of per-broadcast stats
-      # ({ "id", "stats", "subject", "send_at" } hashes), not full broadcasts.
+      # GET /v4/broadcasts/stats — a cursor-paginated list of per-broadcast stats.
       def stats_list(**params)
-        collection("/v4/broadcasts/stats", "broadcasts", Objects::Raw, params)
+        collection("/v4/broadcasts/stats", "broadcasts", Objects::BroadcastStats, params)
       end
 
-      # GET /v4/broadcasts/:id/stats — the raw stats hash for one broadcast.
+      # GET /v4/broadcasts/:id/stats — one broadcast's performance stats.
       def stats(id)
-        http_get("/v4/broadcasts/#{id}/stats").fetch("broadcast")
+        one(:get, "/v4/broadcasts/#{id}/stats", "broadcast", Objects::BroadcastStats)
       end
 
-      # GET /v4/broadcasts/:id/clicks — the raw link-click report ({ "id",
-      # "clicks" => [...] }); accepts pagination params.
+      # GET /v4/broadcasts/:id/clicks — a cursor-paginated Collection of the
+      # broadcast's clicked links. The API nests the array under "broadcast", so
+      # this is built directly rather than through Base#collection.
       def clicks(id, **params)
-        http_get("/v4/broadcasts/#{id}/clicks", params: params).fetch("broadcast")
+        body = http_get("/v4/broadcasts/#{id}/clicks", params: params)
+        rows = body.fetch("broadcast").fetch("clicks").map { |row| Objects::BroadcastClick.from(row) }
+        Collection.new(data: rows, pagination: Pagination.from(body.fetch("pagination"))) do |after|
+          clicks(id, **params, after: after)
+        end
       end
     end
   end

data/lib/kit/resources/subscribers.rb

@@ -45,10 +45,9 @@ module Kit
         collection("/v4/subscribers/#{id}/tags", "tags", Objects::Tag, params)
       end
 
-      # GET /v4/subscribers/:id/stats — engagement stats. Returns the raw
-      # `subscriber` hash ({ "id" => ..., "stats" => { ... } }).
+      # GET /v4/subscribers/:id/stats — the subscriber's engagement stats.
       def stats(id)
-        http_get("/v4/subscribers/#{id}/stats").fetch("subscriber")
+        one(:get, "/v4/subscribers/#{id}/stats", "subscriber", Objects::SubscriberStats)
       end
 
       # POST /v4/subscribers/:id/location — set the subscriber's location

data/lib/kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kit
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/kit-rb.rb

@@ -22,7 +22,6 @@ require "kit/pagination"
 require "kit/oauth/pkce"
 require "kit/oauth/token"
 require "kit/oauth/client"
-require "kit/objects/raw"
 require "kit/objects/account"
 require "kit/objects/creator_profile"
 require "kit/objects/subscriber"
@@ -32,6 +31,11 @@ require "kit/objects/form"
 require "kit/objects/sequence"
 require "kit/objects/sequence_email"
 require "kit/objects/broadcast"
+require "kit/objects/broadcast_stats"
+require "kit/objects/broadcast_click"
+require "kit/objects/subscriber_stats"
+require "kit/objects/email_stats"
+require "kit/objects/growth_stats"
 require "kit/objects/webhook"
 require "kit/objects/webhook_endpoint"
 require "kit/objects/email_template"

data/sig/kit-rb.rbs

@@ -126,9 +126,6 @@ module Kit
   end
 
   module Objects
-    module Raw
-      def self.from: (Hash[String, untyped] hash) -> Hash[String, untyped]
-    end
     class User
       attr_reader email: String?
       attr_reader id: Integer?
@@ -314,6 +311,71 @@ module Kit
       attr_reader stats: Hash[String, untyped]?
       def self.from: (Hash[String, untyped] hash) -> SequenceEmail
     end
+    class BroadcastStats
+      attr_reader id: Integer?
+      attr_reader subject: String?
+      attr_reader send_at: String?
+      attr_reader recipients: Integer?
+      attr_reader open_rate: Numeric?
+      attr_reader emails_opened: Integer?
+      attr_reader click_rate: Numeric?
+      attr_reader unsubscribe_rate: Numeric?
+      attr_reader unsubscribes: Integer?
+      attr_reader total_clicks: Integer?
+      attr_reader show_total_clicks: bool?
+      attr_reader status: String?
+      attr_reader progress: Numeric?
+      attr_reader open_tracking_disabled: bool?
+      attr_reader click_tracking_disabled: bool?
+      def self.from: (Hash[String, untyped] hash) -> BroadcastStats
+    end
+    class BroadcastClick
+      attr_reader id: Integer?
+      attr_reader url: String?
+      attr_reader unique_clicks: Integer?
+      attr_reader click_to_delivery_rate: Numeric?
+      attr_reader click_to_open_rate: Numeric?
+      def self.from: (Hash[String, untyped] hash) -> BroadcastClick
+    end
+    class SubscriberStats
+      attr_reader id: Integer?
+      attr_reader sent: Integer?
+      attr_reader opened: Integer?
+      attr_reader clicked: Integer?
+      attr_reader bounced: Integer?
+      attr_reader open_rate: Numeric?
+      attr_reader click_rate: Numeric?
+      attr_reader last_sent: String?
+      attr_reader last_opened: String?
+      attr_reader last_clicked: String?
+      attr_reader sends_since_last_open: Integer?
+      attr_reader sends_since_last_click: Integer?
+      def self.from: (Hash[String, untyped] hash) -> SubscriberStats
+    end
+    class EmailStats
+      attr_reader sent: Integer?
+      attr_reader clicked: Integer?
+      attr_reader opened: Integer?
+      attr_reader email_stats_mode: String?
+      attr_reader open_tracking_enabled: bool?
+      attr_reader click_tracking_enabled: bool?
+      attr_reader starting: String?
+      attr_reader ending: String?
+      attr_reader open_rate: Numeric?
+      attr_reader click_rate: Numeric?
+      attr_reader unsubscribe_rate: Numeric?
+      attr_reader bounce_rate: Numeric?
+      def self.from: (Hash[String, untyped] hash) -> EmailStats
+    end
+    class GrowthStats
+      attr_reader cancellations: Integer?
+      attr_reader net_new_subscribers: Integer?
+      attr_reader new_subscribers: Integer?
+      attr_reader subscribers: Integer?
+      attr_reader starting: String?
+      attr_reader ending: String?
+      def self.from: (Hash[String, untyped] hash) -> GrowthStats
+    end
     class Subscriber
       attr_reader id: Integer?
       attr_reader first_name: String?
@@ -336,8 +398,8 @@ module Kit
       def colors: () -> Array[String]
       def update_colors: (Array[String] colors) -> Array[String]
       def creator_profile: () -> Objects::CreatorProfile
-      def email_stats: () -> Hash[String, untyped]
-      def growth_stats: (**untyped params) -> Hash[String, untyped]
+      def email_stats: () -> Objects::EmailStats
+      def growth_stats: (**untyped params) -> Objects::GrowthStats
     end
     class Subscribers < Base
       def list: (**untyped params) -> Collection[Objects::Subscriber]
@@ -347,7 +409,7 @@ module Kit
       def unsubscribe: (Integer id) -> Objects::Subscriber
       def filter: (**untyped params) -> Collection[Objects::Subscriber]
       def tags: (Integer id, **untyped params) -> Collection[Objects::Tag]
-      def stats: (Integer id) -> Hash[String, untyped]
+      def stats: (Integer id) -> Objects::SubscriberStats
       def set_location: (Integer id, location: Hash[untyped, untyped]) -> Objects::Subscriber
       def remove_location: (Integer id) -> void
     end
@@ -394,9 +456,9 @@ module Kit
       def create: (**untyped attributes) -> Objects::Broadcast
       def update: (Integer id, **untyped attributes) -> Objects::Broadcast
       def delete: (Integer id) -> void
-      def stats_list: (**untyped params) -> Collection[Hash[String, untyped]]
-      def stats: (Integer id) -> Hash[String, untyped]
-      def clicks: (Integer id, **untyped params) -> Hash[String, untyped]
+      def stats_list: (**untyped params) -> Collection[Objects::BroadcastStats]
+      def stats: (Integer id) -> Objects::BroadcastStats
+      def clicks: (Integer id, **untyped params) -> Collection[Objects::BroadcastClick]
     end
     class EmailTemplates < Base
       def list: (**untyped params) -> Collection[Objects::EmailTemplate]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kit-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Lawrence Lin
@@ -49,18 +49,22 @@ files:
 - lib/kit/oauth/token.rb
 - lib/kit/objects/account.rb
 - lib/kit/objects/broadcast.rb
+- lib/kit/objects/broadcast_click.rb
+- lib/kit/objects/broadcast_stats.rb
 - lib/kit/objects/creator_profile.rb
 - lib/kit/objects/custom_field.rb
+- lib/kit/objects/email_stats.rb
 - lib/kit/objects/email_template.rb
 - lib/kit/objects/form.rb
+- lib/kit/objects/growth_stats.rb
 - lib/kit/objects/post.rb
 - lib/kit/objects/purchase.rb
-- lib/kit/objects/raw.rb
 - lib/kit/objects/segment.rb
 - lib/kit/objects/sequence.rb
 - lib/kit/objects/sequence_email.rb
 - lib/kit/objects/snippet.rb
 - lib/kit/objects/subscriber.rb
+- lib/kit/objects/subscriber_stats.rb
 - lib/kit/objects/tag.rb
 - lib/kit/objects/webhook.rb
 - lib/kit/objects/webhook_endpoint.rb

data/lib/kit/objects/raw.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Kit
-  module Objects
-    # Identity "object" for endpoints that return plain analytics hashes rather
-    # than a modelled resource (e.g. the broadcast-stats list). Lets those lists
-    # flow through Base#collection unchanged while keeping .from uniform.
-    module Raw
-      def self.from(hash) = hash
-    end
-  end
-end