kit-rb 0.0.0 → 0.2.0

data/lib/kit/objects/custom_field.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # 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
+      def self.from(hash)
+        new(id: hash["id"], name: hash["name"], key: hash["key"], label: hash["label"])
+      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/email_template.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # An email template as returned by /v4/email_templates. `is_default` marks the
+    # account's default; `category` groups templates in the UI.
+    EmailTemplate = Data.define(:id, :name, :is_default, :category) do
+      def self.from(hash)
+        new(id: hash["id"], name: hash["name"],
+            is_default: hash["is_default"], category: hash["category"])
+      end
+    end
+  end
+end

data/lib/kit/objects/form.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # A form as returned by /v4/forms. `type` is e.g. "embed"/"hosted"; `uid` is
+    # the public identifier used in embed URLs. `subscriber_count` is present
+    # only when the request asks to include it.
+    Form = Data.define(
+      :id, :name, :created_at, :type, :format,
+      :embed_js, :embed_url, :archived, :uid, :subscriber_count
+    ) do
+      def self.from(hash)
+        new(
+          id: hash["id"], name: hash["name"], created_at: hash["created_at"],
+          type: hash["type"], format: hash["format"], embed_js: hash["embed_js"],
+          embed_url: hash["embed_url"], archived: hash["archived"], uid: hash["uid"],
+          subscriber_count: hash["subscriber_count"]
+        )
+      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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+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.
+    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
+    ) do
+      def self.from(hash)
+        new(
+          id: hash["id"], publication_id: hash["publication_id"], created_at: hash["created_at"],
+          title: hash["title"], slug: hash["slug"], description: hash["description"],
+          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"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/purchase.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # A purchase as returned by /v4/purchases. Monetary fields are numbers in the
+    # purchase `currency`; `products` is the raw line-item array (each with
+    # name/pid/lid/sku/unit_price/quantity).
+    Purchase = Data.define(
+      :id, :transaction_id, :subscriber_id, :status, :email_address, :currency,
+      :transaction_time, :subtotal, :discount, :tax, :total, :products, :source
+    ) do
+      def self.from(hash)
+        new(
+          id: hash["id"], transaction_id: hash["transaction_id"],
+          subscriber_id: hash["subscriber_id"], status: hash["status"],
+          email_address: hash["email_address"], currency: hash["currency"],
+          transaction_time: hash["transaction_time"], subtotal: hash["subtotal"],
+          discount: hash["discount"], tax: hash["tax"], total: hash["total"],
+          products: hash["products"], source: hash["source"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/segment.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # A segment (a saved subscriber filter) as returned by /v4/segments.
+    Segment = Data.define(:id, :name, :created_at) do
+      def self.from(hash)
+        new(id: hash["id"], name: hash["name"], created_at: hash["created_at"])
+      end
+    end
+  end
+end

data/lib/kit/objects/sequence.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # A sequence (formerly "course") as returned by /v4/sequences. Only id, name,
+    # hold, repeat, and created_at are always present; the scheduling fields and
+    # counts appear on full reads, and `stats` only when the request includes it.
+    Sequence = Data.define(
+      :id, :name, :hold, :repeat, :created_at, :updated_at,
+      :email_address, :email_template_id, :send_days, :send_hour, :time_zone,
+      :active, :exclude_subscriber_sources, :email_count, :subscriber_count, :stats
+    ) do
+      def self.from(hash)
+        new(
+          id: hash["id"], name: hash["name"], hold: hash["hold"], repeat: hash["repeat"],
+          created_at: hash["created_at"], updated_at: hash["updated_at"],
+          email_address: hash["email_address"], email_template_id: hash["email_template_id"],
+          send_days: hash["send_days"], send_hour: hash["send_hour"], time_zone: hash["time_zone"],
+          active: hash["active"], exclude_subscriber_sources: hash["exclude_subscriber_sources"],
+          email_count: hash["email_count"], subscriber_count: hash["subscriber_count"],
+          stats: hash["stats"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/sequence_email.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # 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.
+    SequenceEmail = Data.define(
+      :id, :sequence_id, :subject, :preview_text, :email_address, :email_template_id,
+      :published, :position, :delay_value, :delay_unit, :send_days, :stats
+    ) do
+      def self.from(hash)
+        new(
+          id: hash["id"], sequence_id: hash["sequence_id"], subject: hash["subject"],
+          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"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/snippet.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # A snippet (reusable content) as returned by /v4/snippets. `snippet_type` is
+    # "inline" or "document"; `content` holds an inline snippet's body and
+    # `document` a document snippet's; `key` is the reference used in emails.
+    Snippet = Data.define(
+      :id, :name, :snippet_type, :archived, :key,
+      :created_at, :updated_at, :content, :document
+    ) do
+      def self.from(hash)
+        new(
+          id: hash["id"], name: hash["name"], snippet_type: hash["snippet_type"],
+          archived: hash["archived"], key: hash["key"], created_at: hash["created_at"],
+          updated_at: hash["updated_at"], content: hash["content"], document: hash["document"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/subscriber.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+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.
+    Subscriber = Data.define(
+      :id, :first_name, :email_address, :state,
+      :created_at, :canceled_at, :location, :fields
+    ) 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"]
+        )
+      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/objects/tag.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+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
+      def self.from(hash)
+        new(
+          id: hash["id"],
+          name: hash["name"],
+          created_at: hash["created_at"],
+          subscriber_count: hash["subscriber_count"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/webhook.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # A webhook (an automation rule that POSTs to target_url) as returned by
+    # /v4/webhooks. `event` is the raw trigger hash ({ "name" => ..., plus the
+    # optional tag_id/form_id/etc. that scope it }).
+    Webhook = Data.define(:id, :account_id, :event, :target_url) do
+      def self.from(hash)
+        new(id: hash["id"], account_id: hash["account_id"],
+            event: hash["event"], target_url: hash["target_url"])
+      end
+    end
+  end
+end

data/lib/kit/objects/webhook_endpoint.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # 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.
+    WebhookEndpoint = Data.define(
+      :id, :name, :url, :events, :status, :source, :description,
+      :created_by_app, :created_at, :previous_secret_expires_at
+    ) 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"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/pagination.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+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`.
+  Pagination = Data.define(
+    :has_previous_page, :has_next_page, :start_cursor, :end_cursor, :per_page
+  ) do
+    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"]
+      )
+    end
+  end
+
+  # One page of results plus the cursor to fetch the next. `Collection` is
+  # Enumerable over the *current* page; `auto_paging_each` lazily walks every
+  # remaining page by following `end_cursor`, so callers never touch cursors:
+  #
+  #   client.subscribers.list.auto_paging_each { |s| puts s.email_address }
+  #   client.subscribers.list.auto_paging_each.lazy.first(500)
+  #
+  # The block given to `.new` fetches the next Collection from an `after` cursor.
+  class Collection
+    include Enumerable
+
+    attr_reader :data, :pagination
+
+    def initialize(data:, pagination:, &fetch_after)
+      @data = data
+      @pagination = pagination
+      @fetch_after = fetch_after
+    end
+
+    # Iterates the current page only.
+    def each(&)
+      @data.each(&)
+    end
+
+    # The next Collection, or nil when there is no next page.
+    def next_page
+      return nil unless @pagination.has_next_page
+
+      @fetch_after.call(@pagination.end_cursor)
+    end
+
+    # Iterates every item across every remaining page, fetching lazily. Returns
+    # an Enumerator when no block is given (so `.lazy` composes).
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block
+
+      page = self
+      loop do
+        page.data.each(&block)
+        break unless page.pagination.has_next_page
+
+        page = page.next_page
+      end
+    end
+  end
+end

data/lib/kit/resources/account.rb

@@ -9,7 +9,33 @@ module Kit
       #
       # @return [Kit::Objects::AccountInfo]
       def get
-        Objects::AccountInfo.from(super("/v4/account"))
+        Objects::AccountInfo.from(http_get("/v4/account"))
+      end
+
+      # GET /v4/account/colors — the account's brand color palette (hex strings).
+      def colors
+        http_get("/v4/account/colors").fetch("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")
+      end
+
+      # GET /v4/account/creator_profile
+      def creator_profile
+        one(:get, "/v4/account/creator_profile", "profile", Objects::CreatorProfile)
+      end
+
+      # GET /v4/account/email_stats — account-wide email engagement stats.
+      def email_stats
+        one(:get, "/v4/account/email_stats", "stats", Objects::EmailStats)
+      end
+
+      # GET /v4/account/growth_stats — subscriber-growth stats; accepts
+      # starting/ending to bound the window.
+      def growth_stats(**params)
+        one(:get, "/v4/account/growth_stats", "stats", Objects::GrowthStats, params: params)
       end
     end
   end

data/lib/kit/resources/base.rb

@@ -3,7 +3,8 @@
 module Kit
   module Resources
     # Shared base for every resource group. Holds the connection and exposes
-    # thin verb helpers so resource classes read as `get("/v4/account")`.
+    # verb helpers under `http_*` names so a resource can define public methods
+    # like `get(id)` or `list` without colliding with the transport helpers.
     class Base
       def initialize(connection)
         @connection = connection
@@ -11,20 +12,51 @@ module Kit
 
       private
 
-      def get(path, params: {})
+      # Non-enveloped read (whole body) and list reads go through http_get;
+      # deletes return no object and go through http_delete. Enveloped
+      # single-object and list responses are built by `one` and `collection`.
+      def http_get(path, params: {})
         @connection.request(:get, path, params: params)
       end
 
-      def post(path, body: nil, params: {})
+      # Raw POST/PUT for payloads that are not a single wrapped object — the
+      # account colors array, and the bulk endpoints' composite
+      # { <resource>, failures } result. Enveloped objects go through `one`.
+      def http_post(path, body: nil, params: {})
         @connection.request(:post, path, params: params, body: body)
       end
 
-      def put(path, body: nil, params: {})
+      def http_put(path, body: nil, params: {})
         @connection.request(:put, path, params: params, body: body)
       end
 
-      def delete(path, params: {})
-        @connection.request(:delete, path, params: params)
+      # Bulk deletes carry a body (the items to remove), so body is accepted.
+      def http_delete(path, body: nil, params: {})
+        @connection.request(:delete, path, params: params, body: body)
+      end
+
+      # Sends one request that returns a single wrapped object and builds it.
+      # `key` is the envelope key (e.g. "subscriber"), `klass` the object built
+      # via `klass.from`. Centralised so a resource never hand-writes the read/
+      # build/return plumbing — it declares only verb, path, key, class, body.
+      def one(verb, path, key, klass, body: nil, params: {})
+        response = @connection.request(verb, path, params: params, body: body)
+        klass.from(response.fetch(key))
+      end
+
+      # Fetches a cursor-paginated list and wraps it in a Collection whose next
+      # page follows end_cursor. `key` is the array key in the envelope (e.g.
+      # "subscribers"), `klass` the object built from each element. Centralised
+      # here so every list resource paginates identically and correctly.
+      #
+      # `verb`/`body` default to a GET with no body; the POST-based filter
+      # endpoints pass verb: :post with a filter body, still paging by cursor.
+      def collection(path, key, klass, params, verb: :get, body: nil)
+        response = @connection.request(verb, path, params: params, body: body)
+        data = response.fetch(key).map { |element| klass.from(element) }
+        Collection.new(data: data, pagination: Pagination.from(response.fetch("pagination"))) do |after|
+          collection(path, key, klass, params.merge(after: after), verb: verb, body: body)
+        end
       end
     end
   end

data/lib/kit/resources/broadcasts.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Kit
+  module Resources
+    # The /v4/broadcasts endpoints — one-off emails, plus their stats and link
+    # click reports.
+    class Broadcasts < Base
+      # GET /v4/broadcasts
+      def list(**params)
+        collection("/v4/broadcasts", "broadcasts", Objects::Broadcast, params)
+      end
+
+      # GET /v4/broadcasts/:id
+      def get(id)
+        one(:get, "/v4/broadcasts/#{id}", "broadcast", Objects::Broadcast)
+      end
+
+      # POST /v4/broadcasts
+      def create(**attributes)
+        one(:post, "/v4/broadcasts", "broadcast", Objects::Broadcast, body: attributes)
+      end
+
+      # PUT /v4/broadcasts/:id
+      def update(id, **attributes)
+        one(:put, "/v4/broadcasts/#{id}", "broadcast", Objects::Broadcast, body: attributes)
+      end
+
+      # DELETE /v4/broadcasts/:id
+      def delete(id)
+        http_delete("/v4/broadcasts/#{id}")
+        nil
+      end
+
+      # GET /v4/broadcasts/stats — a cursor-paginated list of per-broadcast stats.
+      def stats_list(**params)
+        collection("/v4/broadcasts/stats", "broadcasts", Objects::BroadcastStats, params)
+      end
+
+      # GET /v4/broadcasts/:id/stats — one broadcast's performance stats.
+      def stats(id)
+        one(:get, "/v4/broadcasts/#{id}/stats", "broadcast", Objects::BroadcastStats)
+      end
+
+      # 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)
+        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
+end

data/lib/kit/resources/bulk.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Kit
+  module Resources
+    # The /v4/bulk endpoints — batch operations that all require OAuth. Each call
+    # takes an array of items and an optional callback_url, and returns the raw
+    # result hash: the created/affected items under their resource key plus a
+    # "failures" array. Large batches are processed asynchronously and reported
+    # to callback_url; the response still carries whatever completed inline.
+    class Bulk < Base
+      # POST /v4/bulk/subscribers
+      def create_subscribers(subscribers, callback_url: nil)
+        post("/v4/bulk/subscribers", subscribers: subscribers, callback_url: callback_url)
+      end
+
+      # POST /v4/bulk/custom_fields
+      def create_custom_fields(custom_fields, callback_url: nil)
+        post("/v4/bulk/custom_fields", custom_fields: custom_fields, callback_url: callback_url)
+      end
+
+      # POST /v4/bulk/custom_fields/subscribers
+      def update_custom_field_values(custom_field_values, callback_url: nil)
+        post("/v4/bulk/custom_fields/subscribers",
+             custom_field_values: custom_field_values, callback_url: callback_url)
+      end
+
+      # POST /v4/bulk/forms/subscribers
+      def add_subscribers_to_forms(additions, callback_url: nil)
+        post("/v4/bulk/forms/subscribers", additions: additions, callback_url: callback_url)
+      end
+
+      # POST /v4/bulk/tags
+      def create_tags(tags, callback_url: nil)
+        post("/v4/bulk/tags", tags: tags, callback_url: callback_url)
+      end
+
+      # DELETE /v4/bulk/tags
+      def delete_tags(tags, callback_url: nil)
+        delete("/v4/bulk/tags", tags: tags, callback_url: callback_url)
+      end
+
+      # POST /v4/bulk/tags/subscribers
+      def tag_subscribers(taggings, callback_url: nil)
+        post("/v4/bulk/tags/subscribers", taggings: taggings, callback_url: callback_url)
+      end
+
+      # DELETE /v4/bulk/tags/subscribers
+      def remove_tag_subscribers(taggings, callback_url: nil)
+        delete("/v4/bulk/tags/subscribers", taggings: taggings, callback_url: callback_url)
+      end
+
+      private
+
+      def post(path, **body)
+        http_post(path, body: body.compact)
+      end
+
+      def delete(path, **body)
+        http_delete(path, body: body.compact)
+      end
+    end
+  end
+end