kit-rb 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd1696be6db17ef8f8d6a5c010d7e827bb914f7ea32e1b8e0e68a55f4a548cfc
-  data.tar.gz: f68f531db1eaa19bd17f46f4a764f994419fbf01cf2349d141686f00c33ccc7f
+  metadata.gz: fa9f06f61a89d938cb719fcbd0cad578e8dd6d6ffc35fcf9b17d356f6a9160b3
+  data.tar.gz: 6279b4801b2cd8738b11bcc43babad6b8654739683ace8ff86389e040b8a994b
 SHA512:
-  metadata.gz: fea1917e81a6eef748518e0609b9d0b4e6c5f347b5527d12ba5575dbf02a210ea3db32037163d98e30e83cb6d35a258a0a5a712a969306960ca9ffaedbafe612
-  data.tar.gz: '058e607d279ad4c3f462a50495874c5d4ce8792dc73961ca193488c7e44e5442fc2cb057b3563fc295b382d2184e4c467f4742d1b4478ac4fb1ea7c4a3493d86'
+  metadata.gz: 3cc4008cae00b1fe78391e5816b3e19040103c86b5d4feedbc8a03fdce856325e969840f4d568c583f2f5a1bd579f69ffd403c7e515cfca611a3ea0eca24b636
+  data.tar.gz: 279c04700c82548a16c64637d72269d1ad36a06419228e5ba738e603f98f23983f60183078a79c5a166dee45bc40d5f36a50c4b841a969d020acdaa6bdebf8b7

data/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.1.0] - 2026-09-04
+
+First feature-complete release: the entire Kit API v4 surface — all 81 documented
+operations across every resource — verified against the vendored OpenAPI document.
+
+### Added
+- Full resource coverage via `client.`: `account` (colors, creator_profile,
+  email/growth stats), `subscribers` (list/get/create/update/unsubscribe, filter,
+  tags, stats, location), `tags`, `custom_fields`, `forms`, `sequences` (incl.
+  emails and subscribers), `broadcasts` (incl. stats and click reports),
+  `email_templates`, `segments`, `posts`, `snippets`, `purchases`, `webhooks`,
+  `webhook_endpoints`, and `bulk` (all eight batch operations).
+- OAuth 2.0: `client_credentials` grant and RFC 7009 token `revoke`, alongside
+  the existing authorization-code / refresh / PKCE flows.
+- `Base#one`/`#collection` helpers centralising single-object and cursor-list
+  plumbing (POST-based lists supported for the filter endpoints).
+- Testing layers: WebMock unit specs, an OpenAPI list-envelope contract test,
+  VCR integration cassettes (secrets scrubbed) replayed in CI, `rake smoke`
+  (live read-only), and an opt-in e2e lifecycle. Full RBS + Steep.
+- Trusted Publishing release workflow (GitHub Actions OIDC → RubyGems).
+
 ## [0.0.0] - 2026-09-04
 
 Name-reservation release: the P0 foundation and a working `GET /v4/account`
@@ -16,4 +37,11 @@ vertical slice. Not yet feature-complete — resources land in 0.1.0 per docs/DE
 - `http.rb`-backed `Kit::Connection` with JSON handling and a typed error
   hierarchy (`Kit::AuthenticationError`, `NotFoundError`, `RateLimitError`, …).
 - `GET /v4/account` vertical slice returning immutable `Data` value objects.
+- Tags resource: list, create, update, tag/remove a subscriber, list a tag
+  subscribers.
+- Subscribers resource: list (auto-paginating), get, create, update, unsubscribe.
+- OAuth 2.0 authorization-code flow: `Kit::OAuth::Client` (authorize URL,
+  code exchange, single-use refresh), PKCE (S256) helper, and `Token` object.
+- Cursor pagination engine (`Kit::Collection#auto_paging_each`) and automatic
+  429/5xx retry with backoff.
 - RBS signatures for the public surface.

data/README.md

@@ -4,8 +4,9 @@ A modern, fully-typed Ruby client for the **Kit** (formerly ConvertKit) **API v4
 
 The gem is named `kit-rb`; the public namespace is the clean `Kit`.
 
-> Status: early. P0 (foundations + the `GET /v4/account` vertical slice) is in
-> place; resources are landing per [`docs/DESIGN.md`](docs/DESIGN.md).
+> Status: the full v4 surface is implemented — every one of the 81 documented
+> operations across all resources, verified against the vendored OpenAPI
+> document. See [`docs/DESIGN.md`](docs/DESIGN.md).
 
 ## Install
 
@@ -28,7 +29,6 @@ client = Kit::Client.new(access_token: oauth_access_token)
 
 info = client.account.get       # => Kit::Objects::AccountInfo
 info.account.plan_type          # => "creator_pro"
-info.user.email                 # => "you@example.com"
 ```
 
 Responses are immutable `Data` value objects. Errors are typed:
@@ -38,18 +38,69 @@ begin
   client.account.get
 rescue Kit::AuthenticationError => e   # 401
   warn e.status                        # => 401
-rescue Kit::RateLimitError => e        # 429
+rescue Kit::RateLimitError => e        # 429 — honours Retry-After
   sleep e.retry_after
 rescue Kit::APIError => e              # any other non-2xx
   warn e.errors                        # => ["..."] from Kit's body
 end
 ```
 
-## Development
+Transient failures (429 and 5xx) are retried automatically with backoff.
+
+## Resources
+
+`client.` exposes: `account`, `subscribers`, `tags`, `custom_fields`, `forms`,
+`sequences` (incl. its emails and subscribers), `broadcasts` (incl. stats and
+click reports), `email_templates`, `segments`, `posts`, `snippets`, `purchases`,
+`webhooks`, `webhook_endpoints`, and `bulk`.
+
+### Pagination
+
+List endpoints return a `Kit::Collection` — `Enumerable` over the current page,
+with lazy cursor following:
+
+```ruby
+client.subscribers.list.each { |s| ... }              # current page
+client.subscribers.list.auto_paging_each { |s| ... }  # every page, lazily
+client.subscribers.list(status: "active", per_page: 100)
+```
+
+### OAuth 2.0
+
+```ruby
+oauth = Kit::OAuth::Client.new(client_id: ID, client_secret: SECRET,
+                               redirect_uri: "https://app.example/callback")
+
+redirect_to oauth.authorization_url(state: session_token)   # consent
+token = oauth.exchange_code(params[:code])                  # => Kit::OAuth::Token
+token = oauth.refresh(token.refresh_token)                  # single-use refresh
+oauth.revoke(token.access_token)                            # RFC 7009
+
+client = Kit::Client.new(access_token: token.access_token)
+```
+
+Public clients (SPA/mobile/CLI) use PKCE via `Kit::OAuth::PKCE.generate` and omit
+the client secret. `oauth.client_credentials` mints an app-only token (note: Kit
+rejects it on the resource endpoints — account access needs the consent flow).
+
+## Testing
+
+The suite is layered:
+
+- **Unit** — every method against WebMock stubs.
+- **Contract** — each list resource is pinned to the vendored OpenAPI document,
+  so reading the wrong response envelope fails automatically.
+- **Integration** — real recorded responses (VCR cassettes, secrets scrubbed)
+  replayed in CI, proving the live shapes still parse into our value objects.
+- **Smoke** — `rake smoke` hits every read endpoint live (needs `KIT_API_KEY`).
+- **E2E** — an opt-in (`KIT_E2E=1`) create→update→list→delete lifecycle that
+  cleans up after itself.
+- **Types** — full RBS signatures, checked with Steep.
 
 ```sh
 bin/setup
 bundle exec rake        # spec + rubocop + steep
+bundle exec rake smoke  # live read-only smoke (needs a key)
 ```
 
 ## License

data/Rakefile

@@ -14,4 +14,21 @@ task :steep do
   sh "bundle exec steep check"
 end
 
+namespace :contract do
+  desc "Refresh the vendored Kit OpenAPI document the contract tests pin against"
+  task :fetch do
+    require "open-uri"
+    require_relative "spec/support/openapi_contract"
+    body = URI.parse(OpenAPIContract::SOURCE_URL).read
+    File.write(OpenAPIContract::PATH, body)
+    puts "Fetched #{OpenAPIContract::SOURCE_URL} -> #{OpenAPIContract::PATH} (#{body.bytesize} bytes)"
+  end
+end
+
+desc "Live read-only smoke test against the real API (needs KIT_API_KEY)"
+task :smoke do
+  require_relative "spec/support/smoke"
+  Kit::Smoke.run
+end
+
 task default: %i[spec rubocop steep]

data/lib/kit/client.rb

@@ -21,5 +21,61 @@ module Kit
     def account
       @account ||= Resources::Account.new(@connection)
     end
+
+    def subscribers
+      @subscribers ||= Resources::Subscribers.new(@connection)
+    end
+
+    def tags
+      @tags ||= Resources::Tags.new(@connection)
+    end
+
+    def custom_fields
+      @custom_fields ||= Resources::CustomFields.new(@connection)
+    end
+
+    def forms
+      @forms ||= Resources::Forms.new(@connection)
+    end
+
+    def sequences
+      @sequences ||= Resources::Sequences.new(@connection)
+    end
+
+    def broadcasts
+      @broadcasts ||= Resources::Broadcasts.new(@connection)
+    end
+
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(@connection)
+    end
+
+    def webhook_endpoints
+      @webhook_endpoints ||= Resources::WebhookEndpoints.new(@connection)
+    end
+
+    def email_templates
+      @email_templates ||= Resources::EmailTemplates.new(@connection)
+    end
+
+    def segments
+      @segments ||= Resources::Segments.new(@connection)
+    end
+
+    def posts
+      @posts ||= Resources::Posts.new(@connection)
+    end
+
+    def snippets
+      @snippets ||= Resources::Snippets.new(@connection)
+    end
+
+    def purchases
+      @purchases ||= Resources::Purchases.new(@connection)
+    end
+
+    def bulk
+      @bulk ||= Resources::Bulk.new(@connection)
+    end
   end
 end

data/lib/kit/configuration.rb

@@ -4,14 +4,19 @@ module Kit
   # Immutable per-client configuration. Exactly one credential (api_key or
   # access_token) must be supplied; the matching auth strategy is selected here.
   class Configuration
-    attr_reader :auth, :base_url, :open_timeout, :read_timeout
+    attr_reader :auth, :base_url, :open_timeout, :read_timeout,
+                :max_retries, :retry_backoff, :max_backoff
 
     def initialize(api_key: nil, access_token: nil, base_url: DEFAULT_BASE_URL,
-                   open_timeout: 10, read_timeout: 30)
+                   open_timeout: 10, read_timeout: 30,
+                   max_retries: 2, retry_backoff: 0.5, max_backoff: 30)
       @auth = build_auth(api_key, access_token)
       @base_url = base_url
       @open_timeout = open_timeout
       @read_timeout = read_timeout
+      @max_retries = max_retries       # 0 disables automatic retries
+      @retry_backoff = retry_backoff   # base seconds for exponential backoff
+      @max_backoff = max_backoff       # cap on any single sleep
     end
 
     private

data/lib/kit/connection.rb

@@ -5,35 +5,46 @@ require "json"
 
 module Kit
   # The transport layer: builds requests with http.rb, injects auth and JSON
-  # headers, parses responses, and maps non-2xx statuses onto the typed error
-  # hierarchy. Resources talk to the API only through this.
+  # headers, parses responses, maps non-2xx statuses onto the typed error
+  # hierarchy, and retries transient failures (429 + 5xx) with backoff.
+  # Resources talk to the API only through this.
   class Connection
     JSON_TYPE = "application/json"
+    RETRYABLE = [RateLimitError, ServerError].freeze
 
     def initialize(config)
       @config = config
     end
 
     # Issues a request and returns the parsed JSON body (a Hash) on success.
+    # 429s honour `Retry-After`; 5xx use exponential backoff with jitter; both
+    # give up after `config.max_retries` and re-raise the typed error.
     #
     # @param method [Symbol] :get, :post, :put, :delete
     # @param path [String] e.g. "/v4/account" (leading slash, no host)
     # @param params [Hash] query string params
     # @param body [Hash, nil] JSON request body
     def request(method, path, params: {}, body: nil)
-      response = client.request(
-        method,
-        "#{@config.base_url}#{path}",
-        params: params,
-        json: body
-      )
-      handle(response)
-    rescue HTTP::Error => e
-      raise Error, "HTTP transport error: #{e.message}"
+      attempt = 0
+      begin
+        handle(perform(method, path, params, body))
+      rescue *RETRYABLE => e
+        attempt += 1
+        raise if attempt > @config.max_retries
+
+        backoff_sleep(backoff_for(e, attempt))
+        retry
+      end
     end
 
     private
 
+    def perform(method, path, params, body)
+      client.request(method, "#{@config.base_url}#{path}", params: params, json: body)
+    rescue HTTP::Error => e
+      raise Error, "HTTP transport error: #{e.message}"
+    end
+
     def client
       HTTP
         .headers(default_headers)
@@ -74,5 +85,20 @@ module Kit
         klass.new(status: status, body: body, response: response)
       end
     end
+
+    # Seconds to wait before the next attempt: the server's Retry-After when it
+    # sent one (429), else exponential backoff (base * 2^(n-1)) with jitter,
+    # capped at config.max_backoff.
+    def backoff_for(error, attempt)
+      return error.retry_after if error.is_a?(RateLimitError) && error.retry_after
+
+      base = @config.retry_backoff * (2**(attempt - 1))
+      [base + (rand * @config.retry_backoff), @config.max_backoff].min
+    end
+
+    # Extracted so tests can stub the wait instead of really sleeping.
+    def backoff_sleep(seconds)
+      sleep(seconds)
+    end
   end
 end

data/lib/kit/errors.rb

@@ -52,6 +52,21 @@ module Kit
   # 5xx — a Kit-side failure.
   class ServerError < APIError; end
 
+  # An OAuth token-endpoint failure. `oauth_error` is the RFC 6749 `error` code
+  # (e.g. "invalid_grant") and `error_description` its human-readable detail.
+  class OAuthError < APIError
+    attr_reader :oauth_error, :error_description
+
+    def initialize(status:, body: nil, response: nil)
+      if body.is_a?(Hash)
+        @oauth_error = body["error"]
+        @error_description = body["error_description"]
+      end
+      super(@oauth_error && "OAuth error: #{@oauth_error} (#{@error_description})",
+            status: status, body: body, response: response)
+    end
+  end
+
   # Maps an HTTP status to the most specific error class above.
   class Error
     def self.class_for(status)

data/lib/kit/oauth/client.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "http"
+require "json"
+require "uri"
+
+module Kit
+  module OAuth
+    # Drives the OAuth 2.0 authorization-code flow for a Kit App Store app:
+    # build the authorize URL, exchange the returned code for a Token, and
+    # refresh it. Kit's OAuth grants a third-party app delegated access to a Kit
+    # account owner's data — it is not end-user login for a creator's own site.
+    #
+    #   oauth = Kit::OAuth::Client.new(client_id: ID, client_secret: SECRET,
+    #                                  redirect_uri: "https://app.example/callback")
+    #   redirect_to oauth.authorization_url(state: session_token)
+    #   token = oauth.exchange_code(params[:code])          # Kit::OAuth::Token
+    #   token = oauth.refresh(token.refresh_token)          # single-use refresh
+    #   client = Kit::Client.new(access_token: token.access_token)
+    #
+    # Public clients (SPAs/mobile/CLIs) omit client_secret and use PKCE instead.
+    class Client
+      AUTHORIZE_PATH = "/v4/oauth/authorize"
+      TOKEN_PATH = "/v4/oauth/token"
+      REVOKE_PATH = "/v4/oauth/revoke"
+
+      def initialize(client_id:, client_secret: nil, redirect_uri: nil, base_url: DEFAULT_BASE_URL)
+        raise ConfigurationError, "client_id is required" if client_id.nil? || client_id.empty?
+
+        @client_id = client_id
+        @client_secret = client_secret
+        @redirect_uri = redirect_uri
+        @base_url = base_url
+      end
+
+      # The URL to redirect the Kit account owner to for consent.
+      def authorization_url(scope: "public", state: nil, code_challenge: nil,
+                            code_challenge_method: nil, tenant_name: nil, redirect_uri: @redirect_uri)
+        query = {
+          client_id: @client_id,
+          response_type: "code",
+          redirect_uri: redirect_uri,
+          scope: scope,
+          state: state,
+          code_challenge: code_challenge,
+          code_challenge_method: code_challenge_method,
+          tenant_name: tenant_name
+        }.compact
+        "#{@base_url}#{AUTHORIZE_PATH}?#{URI.encode_www_form(query)}"
+      end
+
+      # Exchanges an authorization code for a Token. Pass code_verifier for PKCE.
+      def exchange_code(code, code_verifier: nil, redirect_uri: @redirect_uri)
+        token_request(
+          grant_type: "authorization_code",
+          code: code,
+          client_id: @client_id,
+          client_secret: @client_secret,
+          redirect_uri: redirect_uri,
+          code_verifier: code_verifier
+        )
+      end
+
+      # Client-credentials grant: exchanges the app's client_id/client_secret for
+      # a Bearer token with no user-consent step. Kit issues one (scope "public",
+      # ~48h, no refresh_token), but — verified 2026-09-04 — that token is
+      # rejected (401) by the v4 resource endpoints: reaching a creator's account
+      # data still requires the authorization-code flow (the app must first be
+      # authorized on that account). Use this only where a bare app token is
+      # expected; for account access, use #authorization_url + #exchange_code.
+      def client_credentials(scope: nil)
+        token_request(
+          grant_type: "client_credentials",
+          client_id: @client_id,
+          client_secret: @client_secret,
+          scope: scope
+        )
+      end
+
+      # Refreshes a token. Kit refresh tokens are single-use; the returned Token
+      # carries a new refresh_token to persist.
+      def refresh(refresh_token)
+        token_request(
+          grant_type: "refresh_token",
+          refresh_token: refresh_token,
+          client_id: @client_id,
+          client_secret: @client_secret
+        )
+      end
+
+      # Revokes an access or refresh token (RFC 7009). Returns true on success;
+      # per the RFC a 200 means the token is no longer valid regardless of its
+      # prior state, so an unknown/expired/already-revoked token also succeeds.
+      # token_type_hint is "access_token" or "refresh_token".
+      def revoke(token, token_type_hint: nil)
+        response = post_form(REVOKE_PATH, token: token, client_id: @client_id,
+                                          client_secret: @client_secret, token_type_hint: token_type_hint)
+        return true if (200..299).cover?(response.status.to_i)
+
+        raise OAuthError.new(status: response.status.to_i, body: parse_body(response), response: response)
+      end
+
+      private
+
+      def token_request(**form)
+        parse_token(post_form(TOKEN_PATH, form))
+      end
+
+      def post_form(path, form)
+        HTTP
+          .headers("Accept" => "application/json", "User-Agent" => "kit-rb/#{Kit::VERSION}")
+          .post("#{@base_url}#{path}", form: form.compact)
+      rescue HTTP::Error => e
+        raise Error, "HTTP transport error: #{e.message}"
+      end
+
+      def parse_body(response)
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def parse_token(response)
+        status = response.status.to_i
+        body = parse_body(response)
+        return Token.from(body) if (200..299).cover?(status) && body
+
+        raise OAuthError.new(status: status, body: body, response: response)
+      end
+    end
+  end
+end

data/lib/kit/oauth/pkce.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "base64"
+
+module Kit
+  module OAuth
+    # RFC 7636 Proof Key for Code Exchange (S256), for public clients (SPAs,
+    # mobile, CLIs) that cannot hold a client_secret. Generate a challenge before
+    # redirecting to the authorize URL, keep the verifier, and send the verifier
+    # on the token exchange:
+    #
+    #   pkce = Kit::OAuth::PKCE.generate
+    #   url  = oauth.authorization_url(code_challenge: pkce.code_challenge,
+    #                                  code_challenge_method: pkce.code_challenge_method)
+    #   # ...redirect, get code back...
+    #   token = oauth.exchange_code(code, code_verifier: pkce.code_verifier)
+    Challenge = Data.define(:code_verifier, :code_challenge, :code_challenge_method)
+
+    # S256 verifier/challenge generation.
+    module PKCE
+      METHOD = "S256"
+
+      # Builds a fresh verifier and its S256 challenge.
+      def self.generate
+        verifier = SecureRandom.urlsafe_base64(64).tr("=", "") # 43–128 unreserved chars
+        Challenge.new(
+          code_verifier: verifier,
+          code_challenge: challenge_for(verifier),
+          code_challenge_method: METHOD
+        )
+      end
+
+      # base64url( SHA256( verifier ) ), unpadded.
+      def self.challenge_for(verifier)
+        digest = Digest::SHA256.digest(verifier)
+        Base64.urlsafe_encode64(digest, padding: false)
+      end
+    end
+  end
+end

data/lib/kit/oauth/token.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kit
+  module OAuth
+    # An OAuth token set from the token endpoint. Kit's refresh tokens are
+    # single-use: every refresh returns a *new* refresh_token, so persist the
+    # whole Token after each exchange/refresh.
+    Token = Data.define(
+      :access_token, :refresh_token, :token_type, :expires_in, :scope, :created_at
+    ) do
+      def self.from(hash)
+        new(
+          access_token: hash["access_token"],
+          refresh_token: hash["refresh_token"],
+          token_type: hash["token_type"],
+          expires_in: hash["expires_in"],
+          scope: hash["scope"],
+          created_at: hash["created_at"]
+        )
+      end
+
+      # Unix time the access token expires, or nil when the fields are absent.
+      def expires_at
+        return nil unless created_at && expires_in
+
+        created_at + expires_in
+      end
+
+      # True once past expiry (with an optional leeway in seconds).
+      def expired?(now: Time.now.to_i, leeway: 0)
+        exp = expires_at
+        return false unless exp
+
+        now >= (exp - leeway)
+      end
+    end
+  end
+end

data/lib/kit/objects/broadcast.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # A broadcast (a one-off email) as returned by /v4/broadcasts. `email_template`
+    # is a nested {id, name} hash; `subscriber_filter` is the raw filter array;
+    # `publication_id` ties a broadcast to its post when it was also published.
+    Broadcast = Data.define(
+      :id, :publication_id, :created_at, :subject, :preview_text, :description,
+      :content, :public, :published_at, :send_at, :thumbnail_alt, :thumbnail_url,
+      :public_url, :email_address, :email_template, :subscriber_filter, :status
+    ) do
+      def self.from(hash)
+        new(
+          id: hash["id"], publication_id: hash["publication_id"], created_at: hash["created_at"],
+          subject: hash["subject"], preview_text: hash["preview_text"], description: hash["description"],
+          content: hash["content"], public: hash["public"], published_at: hash["published_at"],
+          send_at: hash["send_at"], thumbnail_alt: hash["thumbnail_alt"], thumbnail_url: hash["thumbnail_url"],
+          public_url: hash["public_url"], email_address: hash["email_address"],
+          email_template: hash["email_template"], subscriber_filter: hash["subscriber_filter"],
+          status: hash["status"]
+        )
+      end
+    end
+  end
+end

data/lib/kit/objects/creator_profile.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # A creator profile as returned by /v4/account/creator_profile.
+    CreatorProfile = Data.define(:name, :byline, :bio, :image_url, :profile_url) do
+      def self.from(hash)
+        new(name: hash["name"], byline: hash["byline"], bio: hash["bio"],
+            image_url: hash["image_url"], profile_url: hash["profile_url"])
+      end
+    end
+  end
+end

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