kit_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4996d89da108c8784c235ec730e4d2b4137701d41c1942dfa3e6020d0f7c692e
+  data.tar.gz: 95b2e1edd7d2f15effd72df4d75804202a6685b82e08fcd35f485b51219d4f63
+SHA512:
+  metadata.gz: '070426945ce384b443242bc1f72fe3546449fc5bfb05cde203b9bffe62177bdcf82992c5537a79e4881ad70cf0319429bae37f702921067bd35fc3eabb232364'
+  data.tar.gz: 77670b26e8ec2cfd5006e18560f93e69b27199ef2edcd4f2ec2fb5be0cd329218be354b26ae1fc1b47090793e2e8e987375cacd78daddf37ca8c96a520ca4d79

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 — Unreleased
+
+- Initial release: full Kit v4 API surface (subscribers, tags, custom fields,
+  forms, sequences, sequence emails, broadcasts, account, purchases, segments,
+  snippets, posts, email templates, webhooks, bulk operations).
+- High-level `Kit.subscribe` / `Kit.tag` (by name, create-if-missing, cached) /
+  `Kit.unsubscribe` (by email, idempotent) conveniences.
+- `Kit::Simulated` recording driver with an enforced surface-parity guarantee.
+- Zero runtime dependencies.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mike D
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# kit_api
+
+A plain-Ruby client for the [Kit](https://kit.com) (formerly ConvertKit) **v4 API**. Zero runtime dependencies — `Net::HTTP` and stdlib JSON, nothing else — plus a first-class simulated driver so your tests never touch the network.
+
+[![CI](https://github.com/miked-bro/kit_api/actions/workflows/ci.yml/badge.svg)](https://github.com/miked-bro/kit_api/actions/workflows/ci.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+## Installation
+
+```ruby
+gem "kit_api"
+```
+
+## Quickstart
+
+```ruby
+Kit.configure do |config|
+  config.driver = :v4
+  config.api_key = "kit_..."          # from Kit → Settings → Developer
+  # config.access_token = "..."       # or an OAuth token instead
+  # config.logger = Logger.new($stdout)
+end
+
+# High-level conveniences for the common lifecycle:
+Kit.subscribe(email: "sam@example.com", first_name: "Sam", fields: { plan: "pro" })
+# => { subscriber_id: "123" }
+
+Kit.tag(email: "sam@example.com", tag: "customer")   # by tag NAME — created if missing
+Kit.unsubscribe(email: "sam@example.com")
+```
+
+Everything else lives on the client, one method per documented endpoint:
+
+```ruby
+Kit.client.subscribers(status: "active", per_page: 100)
+Kit.client.create_broadcast(subject: "News", content: "<p>Hi!</p>", ...)
+Kit.client.add_subscriber_to_sequence(4, email_address: "sam@example.com")
+```
+
+Or build a client directly, no global config: `Kit::Client.new(api_key: "kit_...")`.
+
+## The full surface
+
+Methods return the parsed JSON body as-is (string keys); `204 No Content` returns `true`. Non-2xx responses raise `Kit::Error`, which carries `#status` and the raw `#body`.
+
+| Resource | Methods |
+| --- | --- |
+| Subscribers | `subscribers` `subscriber` `create_subscriber` `update_subscriber` `unsubscribe_subscriber` `bulk_create_subscribers` `subscriber_stats` `subscriber_tags` `pin_subscriber_location` `update_subscriber_location` `delete_subscriber_location` |
+| Tags | `tags` `create_tag` `update_tag` `tag_subscribers` `tag_subscriber` `untag_subscriber` `bulk_create_tags` `bulk_delete_tags` `bulk_tag_subscribers` `bulk_untag_subscribers` |
+| Custom fields | `custom_fields` `create_custom_field` `update_custom_field` `delete_custom_field` `bulk_create_custom_fields` `bulk_update_subscriber_fields` |
+| Forms | `forms` `form_subscribers` `add_subscriber_to_form` `bulk_add_subscribers_to_forms` |
+| Sequences | `sequences` `sequence` `create_sequence` `update_sequence` `delete_sequence` `sequence_subscribers` `add_subscriber_to_sequence` `sequence_emails` `sequence_email` `create_sequence_email` `update_sequence_email` `delete_sequence_email` |
+| Broadcasts | `broadcasts` `broadcast` `create_broadcast` `update_broadcast` `delete_broadcast` `broadcast_stats` `broadcasts_stats` `broadcast_clicks` |
+| Account | `account` `account_colors` `update_account_colors` `creator_profile` `email_stats` `growth_stats` |
+| Purchases | `purchases` `purchase` `create_purchase` |
+| Webhooks | `webhooks` `webhook` `create_webhook` `update_webhook` `delete_webhook` `rotate_webhook_secret` `revoke_previous_webhook_secret` |
+| And | `segments` · `snippets` `snippet` `create_snippet` `update_snippet` · `posts` `post` · `email_templates` |
+
+Methods that reach a subscriber take either `email_address:` or `subscriber_id:`:
+
+```ruby
+Kit.client.tag_subscriber(5, email_address: "sam@example.com")
+Kit.client.tag_subscriber(5, subscriber_id: 9)
+```
+
+## Pagination
+
+Every list endpoint is cursor-paginated. Pass the cursors straight through:
+
+```ruby
+cursor = nil
+loop do
+  page = Kit.client.subscribers(per_page: 1000, after: cursor)
+  page["subscribers"].each { |subscriber| ... }
+  break unless page.dig("pagination", "has_next_page")
+  cursor = page.dig("pagination", "end_cursor")
+end
+```
+
+## Testing with the simulated driver
+
+The simulated driver mirrors the real client's surface exactly (a test in this gem enforces it), records every call, and talks to no one:
+
+```ruby
+# The default driver is already :simulated — no configuration needed in tests.
+class FunnelTest < ActiveSupport::TestCase
+  setup { Kit::Simulated.reset! }
+
+  test "signing up subscribes the lead" do
+    post signups_path, params: { email: "sam@example.com" }
+
+    subscribe = Kit::Simulated.calls.find { |call| call[:op] == :subscribe }
+    assert_equal "sam@example.com", subscribe[:email]
+  end
+end
+```
+
+`Kit::Simulated.calls` is an array of `{ op:, **arguments }` hashes; `subscribe` returns deterministic ids (`"sim_<sha256 prefix>"`) so records that store a `subscriber_id` behave realistically.
+
+## Rails
+
+```ruby
+# config/initializers/kit.rb
+Kit.configure do |config|
+  config.driver  = Rails.env.production? ? :v4 : :simulated
+  config.api_key = Rails.application.credentials.dig(:kit, :api_key)
+  config.logger  = Rails.logger
+end
+```
+
+## Good to know
+
+- **No automatic retries.** Rate limits (120 requests/minute with an API key, 600 with OAuth) and transient failures raise `Kit::Error`; retry where you understand idempotency — e.g. `retry_on Kit::Error` in an Active Job.
+- **OAuth-only endpoints.** Kit restricts the `bulk_*` methods and `create_purchase` to OAuth tokens; with an API key the API returns its own error.
+- **Tag names are cached.** `Kit.tag`/`Kit.client.tag(email:, tag:)` resolves names to ids once per client. Renaming a tag in the Kit UI mid-process can leave a stale id; reconfigure (or build a fresh client) to flush.
+- **Custom fields must exist.** Values in `fields:` only stick for custom fields already defined in your Kit account — create them in the UI or via `create_custom_field(label: "Plan")`.
+
+## License
+
+[MIT](LICENSE.txt)

data/lib/kit/client/accounts.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Accounts
+      def account
+        request(:get, "/account")
+      end
+
+      def account_colors
+        request(:get, "/account/colors")
+      end
+
+      # Replaces the whole palette (up to 10 hex codes) — include every color to keep.
+      def update_account_colors(colors)
+        request(:put, "/account/colors", body: { colors: colors })
+      end
+
+      def creator_profile
+        request(:get, "/account/creator_profile")
+      end
+
+      def email_stats
+        request(:get, "/account/email_stats")
+      end
+
+      def growth_stats(**params)
+        request(:get, "/account/growth_stats", params: params)
+      end
+    end
+  end
+end

data/lib/kit/client/broadcasts.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Broadcasts
+      def broadcasts(**params)
+        request(:get, "/broadcasts", params: params)
+      end
+
+      def broadcast(id)
+        request(:get, "/broadcasts/#{id}")
+      end
+
+      # send_at: nil leaves it a draft; subscriber_filter targets tags/segments.
+      def create_broadcast(**attributes)
+        request(:post, "/broadcasts", body: attributes)
+      end
+
+      def update_broadcast(id, **attributes)
+        request(:put, "/broadcasts/#{id}", body: attributes)
+      end
+
+      def delete_broadcast(id)
+        request(:delete, "/broadcasts/#{id}")
+      end
+
+      def broadcast_stats(id)
+        request(:get, "/broadcasts/#{id}/stats")
+      end
+
+      # Filters: sent_after/before, status.
+      def broadcasts_stats(**params)
+        request(:get, "/broadcasts/stats", params: params)
+      end
+
+      def broadcast_clicks(id, **params)
+        request(:get, "/broadcasts/#{id}/clicks", params: params)
+      end
+    end
+  end
+end

data/lib/kit/client/custom_fields.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module CustomFields
+      def custom_fields(**params)
+        request(:get, "/custom_fields", params: params)
+      end
+
+      def create_custom_field(label:)
+        request(:post, "/custom_fields", body: { label: label })
+      end
+
+      def update_custom_field(id, label:)
+        request(:put, "/custom_fields/#{id}", body: { label: label })
+      end
+
+      def delete_custom_field(id)
+        request(:delete, "/custom_fields/#{id}")
+      end
+
+      def bulk_create_custom_fields(custom_fields, callback_url: nil)
+        request(:post, "/bulk/custom_fields",
+          body: { custom_fields: custom_fields, callback_url: callback_url }.compact)
+      end
+
+      # Values are { subscriber_id:, subscriber_custom_field_id:, value: } triples.
+      def bulk_update_subscriber_fields(custom_field_values, callback_url: nil)
+        request(:post, "/bulk/custom_fields/subscribers",
+          body: { custom_field_values: custom_field_values, callback_url: callback_url }.compact)
+      end
+    end
+  end
+end

data/lib/kit/client/email_templates.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module EmailTemplates
+      def email_templates(**params)
+        request(:get, "/email_templates", params: params)
+      end
+    end
+  end
+end

data/lib/kit/client/forms.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Forms
+      def forms(**params)
+        request(:get, "/forms", params: params)
+      end
+
+      def form_subscribers(id, **params)
+        request(:get, "/forms/#{id}/subscribers", params: params)
+      end
+
+      def add_subscriber_to_form(form_id, email_address: nil, subscriber_id: nil, referrer: nil)
+        if subscriber_id
+          request(:post, "/forms/#{form_id}/subscribers/#{subscriber_id}", body: { referrer: referrer }.compact)
+        else
+          request(:post, "/forms/#{form_id}/subscribers",
+            body: { email_address: email_address, referrer: referrer }.compact)
+        end
+      end
+
+      # Additions are { form_id:, subscriber_id:, referrer: } objects.
+      def bulk_add_subscribers_to_forms(additions, callback_url: nil)
+        request(:post, "/bulk/forms/subscribers",
+          body: { additions: additions, callback_url: callback_url }.compact)
+      end
+    end
+  end
+end

data/lib/kit/client/posts.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Posts
+      def posts(**params)
+        request(:get, "/posts", params: params)
+      end
+
+      def post(id)
+        request(:get, "/posts/#{id}")
+      end
+    end
+  end
+end

data/lib/kit/client/purchases.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Purchases
+      def purchases(**params)
+        request(:get, "/purchases", params: params)
+      end
+
+      def purchase(id)
+        request(:get, "/purchases/#{id}")
+      end
+
+      # OAuth only. An existing transaction_id appends products instead of duplicating.
+      def create_purchase(**attributes)
+        request(:post, "/purchases", body: { purchase: attributes })
+      end
+    end
+  end
+end

data/lib/kit/client/segments.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Segments
+      def segments(**params)
+        request(:get, "/segments", params: params)
+      end
+    end
+  end
+end

data/lib/kit/client/sequences.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Sequences
+      def sequences(**params)
+        request(:get, "/sequences", params: params)
+      end
+
+      def sequence(id)
+        request(:get, "/sequences/#{id}")
+      end
+
+      def create_sequence(name:, **attributes)
+        request(:post, "/sequences", body: { name: name, **attributes })
+      end
+
+      def update_sequence(id, **attributes)
+        request(:put, "/sequences/#{id}", body: attributes)
+      end
+
+      def delete_sequence(id)
+        request(:delete, "/sequences/#{id}")
+      end
+
+      def sequence_subscribers(id, **params)
+        request(:get, "/sequences/#{id}/subscribers", params: params)
+      end
+
+      def add_subscriber_to_sequence(sequence_id, email_address: nil, subscriber_id: nil)
+        if subscriber_id
+          request(:post, "/sequences/#{sequence_id}/subscribers/#{subscriber_id}")
+        else
+          request(:post, "/sequences/#{sequence_id}/subscribers", body: { email_address: email_address })
+        end
+      end
+
+      def sequence_emails(sequence_id, **params)
+        request(:get, "/sequences/#{sequence_id}/emails", params: params)
+      end
+
+      def sequence_email(sequence_id, id)
+        request(:get, "/sequences/#{sequence_id}/emails/#{id}")
+      end
+
+      def create_sequence_email(sequence_id, subject:, delay_value:, delay_unit:, **attributes)
+        request(:post, "/sequences/#{sequence_id}/emails",
+          body: { subject: subject, delay_value: delay_value, delay_unit: delay_unit, **attributes })
+      end
+
+      def update_sequence_email(sequence_id, id, **attributes)
+        request(:put, "/sequences/#{sequence_id}/emails/#{id}", body: attributes)
+      end
+
+      def delete_sequence_email(sequence_id, id)
+        request(:delete, "/sequences/#{sequence_id}/emails/#{id}")
+      end
+    end
+  end
+end

data/lib/kit/client/snippets.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Snippets
+      def snippets(**params)
+        request(:get, "/snippets", params: params)
+      end
+
+      def snippet(id)
+        request(:get, "/snippets/#{id}")
+      end
+
+      # snippet_type: "inline" takes content:; "block" takes document_attributes:.
+      def create_snippet(name:, **attributes)
+        request(:post, "/snippets", body: { name: name, **attributes })
+      end
+
+      def update_snippet(id, **attributes)
+        request(:put, "/snippets/#{id}", body: attributes)
+      end
+    end
+  end
+end

data/lib/kit/client/subscribers.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Subscribers
+      # Filters: email_address (exact), status, created_after/before,
+      # updated_after/before, sort_field, sort_order, include, slim.
+      def subscribers(**params)
+        request(:get, "/subscribers", params: params)
+      end
+
+      def subscriber(id)
+        request(:get, "/subscribers/#{id}")
+      end
+
+      # Upserts: an existing email_address gets its first_name updated.
+      def create_subscriber(email_address:, **attributes)
+        request(:post, "/subscribers", body: { email_address: email_address, **attributes })
+      end
+
+      def update_subscriber(id, **attributes)
+        request(:put, "/subscribers/#{id}", body: attributes)
+      end
+
+      def unsubscribe_subscriber(id)
+        request(:post, "/subscribers/#{id}/unsubscribe")
+      end
+
+      def bulk_create_subscribers(subscribers, callback_url: nil)
+        request(:post, "/bulk/subscribers", body: { subscribers: subscribers, callback_url: callback_url }.compact)
+      end
+
+      def subscriber_stats(id, **params)
+        request(:get, "/subscribers/#{id}/stats", params: params)
+      end
+
+      def subscriber_tags(id, **params)
+        request(:get, "/subscribers/#{id}/tags", params: params)
+      end
+
+      def pin_subscriber_location(id, **location)
+        request(:post, "/subscribers/#{id}/location", body: { location: location })
+      end
+
+      def update_subscriber_location(id, **location)
+        request(:patch, "/subscribers/#{id}/location", body: { location: location })
+      end
+
+      def delete_subscriber_location(id)
+        request(:delete, "/subscribers/#{id}/location")
+      end
+    end
+  end
+end

data/lib/kit/client/tags.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Tags
+      def tags(**params)
+        request(:get, "/tags", params: params)
+      end
+
+      def create_tag(name)
+        request(:post, "/tags", body: { name: name })
+      end
+
+      def update_tag(id, name:)
+        request(:put, "/tags/#{id}", body: { name: name })
+      end
+
+      def tag_subscribers(id, **params)
+        request(:get, "/tags/#{id}/subscribers", params: params)
+      end
+
+      def tag_subscriber(tag_id, email_address: nil, subscriber_id: nil)
+        if subscriber_id
+          request(:post, "/tags/#{tag_id}/subscribers/#{subscriber_id}")
+        else
+          request(:post, "/tags/#{tag_id}/subscribers", body: { email_address: email_address })
+        end
+      end
+
+      def untag_subscriber(tag_id, email_address: nil, subscriber_id: nil)
+        if subscriber_id
+          request(:delete, "/tags/#{tag_id}/subscribers/#{subscriber_id}")
+        else
+          request(:delete, "/tags/#{tag_id}/subscribers", params: { email_address: email_address })
+        end
+      end
+
+      # Bulk endpoints need OAuth; taggings are { tag_id:, subscriber_id: } pairs.
+      def bulk_create_tags(tags, callback_url: nil)
+        request(:post, "/bulk/tags", body: { tags: tags, callback_url: callback_url }.compact)
+      end
+
+      def bulk_delete_tags(tags, callback_url: nil)
+        request(:delete, "/bulk/tags", body: { tags: tags, callback_url: callback_url }.compact)
+      end
+
+      def bulk_tag_subscribers(taggings, callback_url: nil)
+        request(:post, "/bulk/tags/subscribers", body: { taggings: taggings, callback_url: callback_url }.compact)
+      end
+
+      def bulk_untag_subscribers(taggings, callback_url: nil)
+        request(:delete, "/bulk/tags/subscribers", body: { taggings: taggings, callback_url: callback_url }.compact)
+      end
+    end
+  end
+end

data/lib/kit/client/webhooks.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Kit
+  class Client
+    module Webhooks
+      def webhooks(**params)
+        request(:get, "/webhook_endpoints", params: params)
+      end
+
+      def webhook(id)
+        request(:get, "/webhook_endpoints/#{id}")
+      end
+
+      # The signing secret comes back in plaintext only on this response.
+      def create_webhook(url:, events:, **attributes)
+        request(:post, "/webhook_endpoints", body: { url: url, events: events, **attributes })
+      end
+
+      def update_webhook(id, **attributes)
+        request(:put, "/webhook_endpoints/#{id}", body: attributes)
+      end
+
+      def delete_webhook(id)
+        request(:delete, "/webhook_endpoints/#{id}")
+      end
+
+      def rotate_webhook_secret(id, force: nil)
+        request(:post, "/webhook_endpoints/#{id}/rotate_secret", body: { force: force }.compact)
+      end
+
+      def revoke_previous_webhook_secret(id)
+        request(:post, "/webhook_endpoints/#{id}/revoke_previous_secret")
+      end
+    end
+  end
+end

data/lib/kit/client.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "client/accounts"
+require_relative "client/broadcasts"
+require_relative "client/custom_fields"
+require_relative "client/email_templates"
+require_relative "client/forms"
+require_relative "client/posts"
+require_relative "client/purchases"
+require_relative "client/segments"
+require_relative "client/sequences"
+require_relative "client/snippets"
+require_relative "client/subscribers"
+require_relative "client/tags"
+require_relative "client/webhooks"
+
+module Kit
+  # The real Kit v4 API (https://developers.kit.com). One method per endpoint,
+  # named resources/resource(id)/create_resource/verb_resource; each returns
+  # the parsed JSON body as-is (204s return true). Pagination cursors pass
+  # straight through: subscribers(after: cursor, per_page: 100).
+  class Client
+    include Accounts, Broadcasts, CustomFields, EmailTemplates, Forms, Posts,
+            Purchases, Segments, Sequences, Snippets, Subscribers, Tags, Webhooks
+
+    def initialize(api_key: nil, access_token: nil, base_url: "https://api.kit.com/v4",
+                   open_timeout: 10, read_timeout: 20)
+      raise Error, "Kit needs an api_key or an OAuth access_token" if api_key.nil? && access_token.nil?
+
+      @api_key = api_key
+      @access_token = access_token
+      @base_url = base_url
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # High-level conveniences, composed from the endpoint methods below.
+
+    def subscribe(email:, first_name:, fields: {})
+      body = create_subscriber(email_address: email, first_name: first_name, fields: fields)
+      { subscriber_id: body.dig("subscriber", "id")&.to_s }
+    end
+
+    # Tags by name: resolved to an id once per client (created if missing) and
+    # cached for the life of the process. Reconfiguring flushes the cache.
+    def tag(email:, tag:)
+      tag_subscriber(tag_id(tag), email_address: email)
+      true
+    end
+
+    # The v4 API unsubscribes by subscriber id only, so look the id up first.
+    # An address Kit doesn't know is already unsubscribed — succeed quietly.
+    def unsubscribe(email:)
+      subscriber = subscribers(email_address: email).fetch("subscribers", []).first
+      return true unless subscriber
+
+      unsubscribe_subscriber(subscriber["id"])
+    end
+
+    private
+      def tag_id(name)
+        @tag_ids ||= {}
+        @tag_ids[name] ||= begin
+          existing, cursor = nil, nil
+          loop do
+            page = tags(per_page: 1000, after: cursor)
+            existing = page.fetch("tags", []).find { |t| t["name"] == name }
+            cursor = page.dig("pagination", "end_cursor")
+            break if existing || !page.dig("pagination", "has_next_page")
+          end
+          (existing || create_tag(name).fetch("tag"))["id"]
+        end
+      end
+
+      VERBS = {
+        get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put,
+        patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
+      }.freeze
+
+      def request(method, path, params: nil, body: nil)
+        uri = URI("#{@base_url}#{path}")
+        query = params&.compact
+        uri.query = URI.encode_www_form(query) unless query.nil? || query.empty?
+
+        req = VERBS.fetch(method).new(uri.request_uri)
+        if @access_token
+          req["Authorization"] = "Bearer #{@access_token}"
+        else
+          req["X-Kit-Api-Key"] = @api_key
+        end
+        req["Accept"] = "application/json"
+        if body
+          req["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+
+        response = http.request(req)
+        unless response.code.start_with?("2")
+          raise Error.new("Kit API #{response.code}: #{response.body.to_s[0, 200]}",
+            status: response.code.to_i, body: response.body)
+        end
+
+        response.body.to_s.empty? ? true : JSON.parse(response.body)
+      end
+  end
+end

data/lib/kit/simulated.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Kit
+  # Dev/test driver: records every call, invents ids, talks to no one. Same
+  # public surface as Client (a test enforces parity), so code under test can
+  # assert on Kit::Simulated.calls instead of stubbing HTTP:
+  #
+  #   Kit::Simulated.reset!
+  #   Kit.subscribe(email: "sam@example.com", first_name: "Sam")
+  #   Kit::Simulated.calls  # => [{ op: :subscribe, email: "sam@example.com", ... }]
+  class Simulated
+    def self.calls = @calls ||= []
+    def self.reset! = @calls = []
+
+    PAGE = { "has_previous_page" => false, "has_next_page" => false,
+             "start_cursor" => nil, "end_cursor" => nil, "per_page" => 500 }.freeze
+
+    # High-level conveniences
+
+    def subscribe(email:, first_name:, fields: {})
+      record(:subscribe, email: email, first_name: first_name, fields: fields)
+      { subscriber_id: sim_id(email) }
+    end
+
+    def tag(email:, tag:)
+      record(:tag, email: email, tag: tag)
+      true
+    end
+
+    def unsubscribe(email:)
+      record(:unsubscribe, email: email)
+      true
+    end
+
+    # Subscribers
+
+    def subscribers(**params) = record_page(:subscribers, "subscribers", **params)
+    def subscriber(id) = record_one(:subscriber, "subscriber", id, id: id)
+
+    def create_subscriber(email_address:, **attributes)
+      record(:create_subscriber, email_address: email_address, **attributes)
+      { "subscriber" => { "id" => sim_id(email_address), "email_address" => email_address,
+                          "state" => "active", **attributes.transform_keys(&:to_s) } }
+    end
+
+    def update_subscriber(id, **attributes) = record_one(:update_subscriber, "subscriber", id, id: id, **attributes)
+    def unsubscribe_subscriber(id) = record(:unsubscribe_subscriber, id: id)
+    def bulk_create_subscribers(subscribers, callback_url: nil) = record_bulk(:bulk_create_subscribers, subscribers: subscribers, callback_url: callback_url)
+    def subscriber_stats(id, **params) = record_one(:subscriber_stats, "subscriber", id, id: id, **params)
+    def subscriber_tags(id, **params) = record_page(:subscriber_tags, "tags", id: id, **params)
+    def pin_subscriber_location(id, **location) = record_one(:pin_subscriber_location, "subscriber", id, id: id, **location)
+    def update_subscriber_location(id, **location) = record_one(:update_subscriber_location, "subscriber", id, id: id, **location)
+    def delete_subscriber_location(id) = record(:delete_subscriber_location, id: id)
+
+    # Tags
+
+    def tags(**params) = record_page(:tags, "tags", **params)
+
+    def create_tag(name)
+      record(:create_tag, name: name)
+      { "tag" => { "id" => sim_id(name), "name" => name } }
+    end
+
+    def update_tag(id, name:) = record_one(:update_tag, "tag", id, id: id, name: name)
+    def tag_subscribers(id, **params) = record_page(:tag_subscribers, "subscribers", id: id, **params)
+
+    def tag_subscriber(tag_id, email_address: nil, subscriber_id: nil)
+      record(:tag_subscriber, tag_id: tag_id, email_address: email_address, subscriber_id: subscriber_id)
+      { "subscriber" => { "id" => subscriber_id || sim_id(email_address.to_s) } }
+    end
+
+    def untag_subscriber(tag_id, email_address: nil, subscriber_id: nil)
+      record(:untag_subscriber, tag_id: tag_id, email_address: email_address, subscriber_id: subscriber_id)
+    end
+
+    def bulk_create_tags(tags, callback_url: nil) = record_bulk(:bulk_create_tags, tags: tags, callback_url: callback_url)
+    def bulk_delete_tags(tags, callback_url: nil) = record_bulk(:bulk_delete_tags, tags: tags, callback_url: callback_url)
+    def bulk_tag_subscribers(taggings, callback_url: nil) = record_bulk(:bulk_tag_subscribers, taggings: taggings, callback_url: callback_url)
+    def bulk_untag_subscribers(taggings, callback_url: nil) = record_bulk(:bulk_untag_subscribers, taggings: taggings, callback_url: callback_url)
+
+    # Custom fields
+
+    def custom_fields(**params) = record_page(:custom_fields, "custom_fields", **params)
+
+    def create_custom_field(label:)
+      record(:create_custom_field, label: label)
+      { "custom_field" => { "id" => sim_id(label), "label" => label } }
+    end
+
+    def update_custom_field(id, label:) = record_one(:update_custom_field, "custom_field", id, id: id, label: label)
+    def delete_custom_field(id) = record(:delete_custom_field, id: id)
+    def bulk_create_custom_fields(custom_fields, callback_url: nil) = record_bulk(:bulk_create_custom_fields, custom_fields: custom_fields, callback_url: callback_url)
+    def bulk_update_subscriber_fields(custom_field_values, callback_url: nil) = record_bulk(:bulk_update_subscriber_fields, custom_field_values: custom_field_values, callback_url: callback_url)
+
+    # Forms
+
+    def forms(**params) = record_page(:forms, "forms", **params)
+    def form_subscribers(id, **params) = record_page(:form_subscribers, "subscribers", id: id, **params)
+
+    def add_subscriber_to_form(form_id, email_address: nil, subscriber_id: nil, referrer: nil)
+      record(:add_subscriber_to_form, form_id: form_id, email_address: email_address,
+        subscriber_id: subscriber_id, referrer: referrer)
+      { "subscriber" => { "id" => subscriber_id || sim_id(email_address.to_s) } }
+    end
+
+    def bulk_add_subscribers_to_forms(additions, callback_url: nil) = record_bulk(:bulk_add_subscribers_to_forms, additions: additions, callback_url: callback_url)
+
+    # Sequences
+
+    def sequences(**params) = record_page(:sequences, "sequences", **params)
+    def sequence(id) = record_one(:sequence, "sequence", id, id: id)
+
+    def create_sequence(name:, **attributes)
+      record(:create_sequence, name: name, **attributes)
+      { "sequence" => { "id" => sim_id(name), "name" => name } }
+    end
+
+    def update_sequence(id, **attributes) = record_one(:update_sequence, "sequence", id, id: id, **attributes)
+    def delete_sequence(id) = record(:delete_sequence, id: id)
+    def sequence_subscribers(id, **params) = record_page(:sequence_subscribers, "subscribers", id: id, **params)
+
+    def add_subscriber_to_sequence(sequence_id, email_address: nil, subscriber_id: nil)
+      record(:add_subscriber_to_sequence, sequence_id: sequence_id, email_address: email_address,
+        subscriber_id: subscriber_id)
+      { "subscriber" => { "id" => subscriber_id || sim_id(email_address.to_s) } }
+    end
+
+    def sequence_emails(sequence_id, **params) = record_page(:sequence_emails, "emails", sequence_id: sequence_id, **params)
+    def sequence_email(sequence_id, id) = record_one(:sequence_email, "email", id, sequence_id: sequence_id, id: id)
+
+    def create_sequence_email(sequence_id, subject:, delay_value:, delay_unit:, **attributes)
+      record(:create_sequence_email, sequence_id: sequence_id, subject: subject,
+        delay_value: delay_value, delay_unit: delay_unit, **attributes)
+      { "email" => { "id" => sim_id(subject), "sequence_id" => sequence_id, "subject" => subject } }
+    end
+
+    def update_sequence_email(sequence_id, id, **attributes) = record_one(:update_sequence_email, "email", id, sequence_id: sequence_id, id: id, **attributes)
+    def delete_sequence_email(sequence_id, id) = record(:delete_sequence_email, sequence_id: sequence_id, id: id)
+
+    # Broadcasts
+
+    def broadcasts(**params) = record_page(:broadcasts, "broadcasts", **params)
+    def broadcast(id) = record_one(:broadcast, "broadcast", id, id: id)
+
+    def create_broadcast(**attributes)
+      record(:create_broadcast, **attributes)
+      { "broadcast" => { "id" => sim_id(attributes.inspect), **attributes.transform_keys(&:to_s) } }
+    end
+
+    def update_broadcast(id, **attributes) = record_one(:update_broadcast, "broadcast", id, id: id, **attributes)
+    def delete_broadcast(id) = record(:delete_broadcast, id: id)
+    def broadcast_stats(id) = record_one(:broadcast_stats, "broadcast", id, id: id)
+    def broadcasts_stats(**params) = record_page(:broadcasts_stats, "broadcasts", **params)
+    def broadcast_clicks(id, **params) = record_one(:broadcast_clicks, "broadcast", id, id: id, **params)
+
+    # Account
+
+    def account = record_one(:account, "account", "sim_account")
+    def account_colors = (record(:account_colors); { "colors" => [] })
+    def update_account_colors(colors) = (record(:update_account_colors, colors: colors); { "colors" => colors })
+    def creator_profile = record_one(:creator_profile, "profile", "sim_profile")
+    def email_stats = record_one(:email_stats, "stats", "sim_stats")
+    def growth_stats(**params) = record_one(:growth_stats, "stats", "sim_stats", **params)
+
+    # Purchases
+
+    def purchases(**params) = record_page(:purchases, "purchases", **params)
+    def purchase(id) = record_one(:purchase, "purchase", id, id: id)
+
+    def create_purchase(**attributes)
+      record(:create_purchase, **attributes)
+      { "purchase" => { "id" => sim_id(attributes.inspect), **attributes.transform_keys(&:to_s) } }
+    end
+
+    # Segments, snippets, posts, email templates
+
+    def segments(**params) = record_page(:segments, "segments", **params)
+    def snippets(**params) = record_page(:snippets, "snippets", **params)
+    def snippet(id) = record_one(:snippet, "snippet", id, id: id)
+
+    def create_snippet(name:, **attributes)
+      record(:create_snippet, name: name, **attributes)
+      { "snippet" => { "id" => sim_id(name), "name" => name } }
+    end
+
+    def update_snippet(id, **attributes) = record_one(:update_snippet, "snippet", id, id: id, **attributes)
+    def posts(**params) = record_page(:posts, "posts", **params)
+    def post(id) = record_one(:post, "post", id, id: id)
+    def email_templates(**params) = record_page(:email_templates, "email_templates", **params)
+
+    # Webhooks
+
+    def webhooks(**params) = record_page(:webhooks, "webhook_endpoints", **params)
+    def webhook(id) = record_one(:webhook, "webhook_endpoint", id, id: id)
+
+    def create_webhook(url:, events:, **attributes)
+      record(:create_webhook, url: url, events: events, **attributes)
+      { "webhook_endpoint" => { "id" => sim_id(url), "url" => url, "events" => events, "secret" => "whsec_simulated" } }
+    end
+
+    def update_webhook(id, **attributes) = record_one(:update_webhook, "webhook_endpoint", id, id: id, **attributes)
+    def delete_webhook(id) = record(:delete_webhook, id: id)
+    def rotate_webhook_secret(id, force: nil) = record_one(:rotate_webhook_secret, "webhook_endpoint", id, id: id, force: force)
+    def revoke_previous_webhook_secret(id) = record_one(:revoke_previous_webhook_secret, "webhook_endpoint", id, id: id)
+
+    private
+      def record(op, **kwargs)
+        self.class.calls << { op: op, **kwargs }
+        Kit.config.logger&.info("[Kit simulated] #{op} #{kwargs.values.first}")
+        true
+      end
+
+      def record_page(op, key, **kwargs)
+        record(op, **kwargs)
+        { key => [], "pagination" => PAGE.dup }
+      end
+
+      def record_one(op, key, id, **kwargs)
+        record(op, **kwargs)
+        { key => { "id" => id } }
+      end
+
+      def record_bulk(op, **kwargs)
+        record(op, **kwargs.compact)
+        { "failures" => [] }
+      end
+
+      def sim_id(seed) = "sim_#{Digest::SHA256.hexdigest(seed.to_s)[0, 12]}"
+  end
+end

data/lib/kit/version.rb

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

data/lib/kit.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "kit/version"
+require_relative "kit/client"
+require_relative "kit/simulated"
+
+# Kit (ConvertKit) v4 API client. Configure once, then call the high-level
+# conveniences on the module or reach the full API surface via Kit.client.
+#
+#   Kit.configure do |config|
+#     config.driver = :v4
+#     config.api_key = "kit_..."
+#   end
+#
+#   Kit.subscribe(email: "sam@example.com", first_name: "Sam")
+#   Kit.client.broadcasts(per_page: 10)
+module Kit
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+
+  Config = Struct.new(:api_key, :access_token, :driver, :logger,
+                      :open_timeout, :read_timeout, :base_url)
+
+  def self.config
+    @config ||= Config.new(nil, nil, :simulated, nil, 10, 20, "https://api.kit.com/v4")
+  end
+
+  def self.configure
+    yield config
+    @client = nil
+  end
+
+  # Plain ||= — concurrent first-touch can build a redundant client, which is
+  # harmless (stateless but for the tag-name cache). Configure at boot.
+  def self.client
+    @client ||= case config.driver
+    when :v4
+      Client.new(api_key: config.api_key, access_token: config.access_token,
+        base_url: config.base_url, open_timeout: config.open_timeout,
+        read_timeout: config.read_timeout)
+    when :simulated
+      Simulated.new
+    else
+      raise Error, "Unknown Kit driver: #{config.driver.inspect} (use :v4 or :simulated)"
+    end
+  end
+
+  def self.reset! = (@config = nil; @client = nil)
+
+  def self.subscribe(email:, first_name:, fields: {})
+    client.subscribe(email: email, first_name: first_name, fields: fields)
+  end
+
+  def self.tag(email:, tag:)
+    client.tag(email: email, tag: tag)
+  end
+
+  def self.unsubscribe(email:)
+    client.unsubscribe(email: email)
+  end
+end

data/lib/kit_api.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The gem is named kit_api ("kit" was taken on rubygems) but defines the Kit
+# module. This shim keeps Bundler's default require working.
+require_relative "kit"

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: kit_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mike D
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'A plain-Ruby client for the Kit (formerly ConvertKit) v4 API: subscribers,
+  tags, custom fields, forms, sequences, broadcasts, purchases, webhooks and more.
+  Net::HTTP and stdlib JSON only, plus a first-class simulated driver for tests.'
+email:
+- mojonickle@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/kit.rb
+- lib/kit/client.rb
+- lib/kit/client/accounts.rb
+- lib/kit/client/broadcasts.rb
+- lib/kit/client/custom_fields.rb
+- lib/kit/client/email_templates.rb
+- lib/kit/client/forms.rb
+- lib/kit/client/posts.rb
+- lib/kit/client/purchases.rb
+- lib/kit/client/segments.rb
+- lib/kit/client/sequences.rb
+- lib/kit/client/snippets.rb
+- lib/kit/client/subscribers.rb
+- lib/kit/client/tags.rb
+- lib/kit/client/webhooks.rb
+- lib/kit/simulated.rb
+- lib/kit/version.rb
+- lib/kit_api.rb
+homepage: https://github.com/miked-bro/kit_api
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/miked-bro/kit_api
+  changelog_uri: https://github.com/miked-bro/kit_api/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Kit (ConvertKit) v4 API client with zero dependencies.
+test_files: []