rcs 2.0.16 → 2.0.18

data/lib/pinnacle/internal/types/utils.rb

@@ -81,10 +81,10 @@ module Pinnacle
                }
               return type.coerce(value, strict: strict)
             else
-              value
+              value # rubocop:disable Lint/Void
             end
           else
-            value
+            value # rubocop:disable Lint/Void
           end
 
           raise Errors::TypeError, "cannot coerce value of type `#{value.class}` to `#{target}`" if strict

data/lib/pinnacle/messages/client.rb

@@ -27,7 +27,7 @@ module Pinnacle
         request = Pinnacle::Internal::JSON::Request.new(
           base_url: request_options[:base_url],
           method: "GET",
-          path: "messages/#{params[:id]}",
+          path: "messages/#{URI.encode_uri_component(params[:id].to_s)}",
           request_options: request_options
         )
         begin

data/lib/pinnacle/messages/schedule/client.rb

@@ -31,7 +31,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "DELETE",
-            path: "messages/schedule/#{params[:id]}",
+            path: "messages/schedule/#{URI.encode_uri_component(params[:id].to_s)}",
             request_options: request_options
           )
           begin

data/lib/pinnacle/rcs/client.rb

@@ -30,7 +30,7 @@ module Pinnacle
         request = Pinnacle::Internal::JSON::Request.new(
           base_url: request_options[:base_url],
           method: "GET",
-          path: "rcs/#{params[:agent_id]}",
+          path: "rcs/#{URI.encode_uri_component(params[:agent_id].to_s)}",
           request_options: request_options
         )
         begin

data/lib/pinnacle/rcs/test/client.rb

@@ -115,7 +115,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "PATCH",
-            path: "rcs/test/agents/#{params[:agent_id]}",
+            path: "rcs/test/agents/#{URI.encode_uri_component(params[:agent_id].to_s)}",
             body: body,
             request_options: request_options
           )
@@ -186,7 +186,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "POST",
-            path: "rcs/test/agents/#{params[:agent_id]}/whitelist",
+            path: "rcs/test/agents/#{URI.encode_uri_component(params[:agent_id].to_s)}/whitelist",
             body: body,
             request_options: request_options
           )
@@ -252,7 +252,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "GET",
-            path: "rcs/test/agents/#{params[:agent_id]}/numbers",
+            path: "rcs/test/agents/#{URI.encode_uri_component(params[:agent_id].to_s)}/numbers",
             query: query_params,
             request_options: request_options
           )

data/lib/pinnacle/status/get/client.rb

@@ -28,7 +28,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "GET",
-            path: "status/brand/#{params[:brand_id]}",
+            path: "status/brand/#{URI.encode_uri_component(params[:brand_id].to_s)}",
             request_options: request_options
           )
           begin
@@ -62,7 +62,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "GET",
-            path: "status/toll-free-campaign/#{params[:campaign_id]}",
+            path: "status/toll-free-campaign/#{URI.encode_uri_component(params[:campaign_id].to_s)}",
             request_options: request_options
           )
           begin
@@ -96,7 +96,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "GET",
-            path: "status/dlc-campaign/#{params[:campaign_id]}",
+            path: "status/dlc-campaign/#{URI.encode_uri_component(params[:campaign_id].to_s)}",
             request_options: request_options
           )
           begin
@@ -130,7 +130,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "GET",
-            path: "status/rcs-campaign/#{params[:campaign_id]}",
+            path: "status/rcs-campaign/#{URI.encode_uri_component(params[:campaign_id].to_s)}",
             request_options: request_options
           )
           begin
@@ -166,7 +166,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "GET",
-            path: "status/phone-number/#{params[:phone_number]}",
+            path: "status/phone-number/#{URI.encode_uri_component(params[:phone_number].to_s)}",
             request_options: request_options
           )
           begin

data/lib/pinnacle/tools/url/client.rb

@@ -62,7 +62,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "GET",
-            path: "tools/url/#{params[:link_id]}",
+            path: "tools/url/#{URI.encode_uri_component(params[:link_id].to_s)}",
             request_options: request_options
           )
           begin
@@ -101,7 +101,7 @@ module Pinnacle
           request = Pinnacle::Internal::JSON::Request.new(
             base_url: request_options[:base_url],
             method: "PUT",
-            path: "tools/url/#{params[:link_id]}",
+            path: "tools/url/#{URI.encode_uri_component(params[:link_id].to_s)}",
             body: body,
             request_options: request_options
           )

data/lib/pinnacle/types/address_field.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Free-form text input backed by a client-side Google Places autocomplete. Shares text-field validation (length /
+    # pattern); the place lookup happens entirely in the browser and is purely for suggestion UX.
+    class AddressField < Internal::Types::Model
+      field :placeholder, -> { String }, optional: true, nullable: false
+      field :pattern, -> { String }, optional: true, nullable: false
+      field :min_length, -> { Integer }, optional: true, nullable: false
+      field :max_length, -> { Integer }, optional: true, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/agent_summary_carrier_launches.rb

@@ -2,12 +2,18 @@
 
 module Pinnacle
   module Types
-    # Per-carrier launch status for the agent.
+    # Raw per-carrier launch + verification state for the agent. Each
+    # value is tri-state — `null` means "no launch requested" or "not
+    # sent yet"; `false` means "pending" / "sent"; `true` means
+    # "launched" / "verified". Use the [GET /rcs/{agentId}](/api-reference/rcs-agents/get)
+    # endpoint for the resolved enum representation.
     class AgentSummaryCarrierLaunches < Internal::Types::Model
       field :att, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "ATT"
       field :others, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "OTHERS"
       field :tmobile, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "TMOBILE"
       field :verizon, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "VERIZON"
+      field :aegis, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "AEGIS"
+      field :google, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "GOOGLE"
     end
   end
 end

data/lib/pinnacle/types/campaign_status_event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Webhook body delivered to subscribers of `CAMPAIGN.STATUS` whenever
+    # an RCS campaign's per-carrier launch status or verification status
+    # (AEGIS / Google) changes. `CAMPAIGN.STATUS` is only supported for
+    # RCS agent senders — the attach call rejects phone-number senders
+    # with `400 Bad Request`. Verify the `PINNACLE-SIGNING-SECRET` header
+    # matches the signing secret of the webhook this event was delivered
+    # to before trusting the payload.
+    class CampaignStatusEvent < Internal::Types::Model
+      field :type, -> { String }, optional: false, nullable: false
+      field :agent, -> { Pinnacle::Types::CampaignStatusEventAgent }, optional: false, nullable: false
+      field :campaign, -> { Pinnacle::Types::CampaignStatusEventCampaign }, optional: false, nullable: false
+      field :brand, -> { Pinnacle::Types::CampaignStatusEventBrand }, optional: false, nullable: false
+      field :carrier_launches, -> { Pinnacle::Types::CampaignStatusEventCarrierLaunches }, optional: false, nullable: false, api_name: "carrierLaunches"
+      field :updated_at, -> { String }, optional: false, nullable: false, api_name: "updatedAt"
+    end
+  end
+end

data/lib/pinnacle/types/campaign_status_event_agent.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # The RCS agent the campaign-status update is for.
+    class CampaignStatusEventAgent < Internal::Types::Model
+      field :id, -> { String }, optional: false, nullable: false
+      field :name, -> { String }, optional: false, nullable: true
+    end
+  end
+end

data/lib/pinnacle/types/campaign_status_event_brand.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Reference to the brand owning the agent's connected campaign.
+    class CampaignStatusEventBrand < Internal::Types::Model
+      field :public_id, -> { String }, optional: false, nullable: true, api_name: "publicId"
+      field :name, -> { String }, optional: false, nullable: true
+    end
+  end
+end

data/lib/pinnacle/types/campaign_status_event_campaign.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Reference to the connected campaign.
+    class CampaignStatusEventCampaign < Internal::Types::Model
+      field :public_id, -> { String }, optional: false, nullable: true, api_name: "publicId"
+      field :type, -> { Pinnacle::Types::CampaignStatusEventCampaignType }, optional: false, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/campaign_status_event_campaign_type.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    module CampaignStatusEventCampaignType
+      extend Pinnacle::Internal::Types::Enum
+
+      RCS = "RCS"
+      TOLL_FREE = "TOLL_FREE"
+      TEN_DLC = "10DLC"
+    end
+  end
+end

data/lib/pinnacle/types/campaign_status_event_carrier_launches.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Resolved per-key launch status for the campaign's agent. Carrier
+    # statuses live under `carriers` and verifier statuses under
+    # `verification`.
+    class CampaignStatusEventCarrierLaunches < Internal::Types::Model
+      field :carriers, -> { Pinnacle::Types::CampaignStatusEventCarrierLaunchesCarriers }, optional: false, nullable: false
+      field :verification, -> { Pinnacle::Types::CampaignStatusEventCarrierLaunchesVerification }, optional: false, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/campaign_status_event_carrier_launches_carriers.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Per-carrier launch status. Each carrier moves through
+    # `NOT_LAUNCHED` → `PENDING` → `LAUNCHED` as Pinnacle submits the
+    # agent for review and the carrier accepts it. The agent is only
+    # deliverable on a carrier once that carrier reports `LAUNCHED`.
+    class CampaignStatusEventCarrierLaunchesCarriers < Internal::Types::Model
+      field :att, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "ATT"
+      field :tmobile, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "TMOBILE"
+      field :verizon, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "VERIZON"
+      field :others, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "OTHERS"
+    end
+  end
+end

data/lib/pinnacle/types/campaign_status_event_carrier_launches_verification.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # External verifier status. AEGIS (the U.S. carrier vetting
+    # authority used by AT&T, T-Mobile, and Verizon) and Google each
+    # send a verification email to the brand's contact address. Each
+    # verifier moves through `NOT_SENT` → `SENT` → `VERIFIED` once
+    # the brand replies and the verifier confirms ownership.
+    class CampaignStatusEventCarrierLaunchesVerification < Internal::Types::Model
+      field :aegis, -> { Pinnacle::Types::VerificationStatus }, optional: false, nullable: false, api_name: "AEGIS"
+      field :google, -> { Pinnacle::Types::VerificationStatus }, optional: false, nullable: false, api_name: "GOOGLE"
+    end
+  end
+end

data/lib/pinnacle/types/carrier_launches.rb

@@ -2,12 +2,12 @@
 
 module Pinnacle
   module Types
-    # Per-carrier launch status.
+    # Per-carrier launch status grouped by category. `carriers` covers
+    # AT&T / T-Mobile / Verizon / other carriers; `verification` covers
+    # the AEGIS and Google verification flows.
     class CarrierLaunches < Internal::Types::Model
-      field :att, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "ATT"
-      field :tmobile, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "TMOBILE"
-      field :verizon, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "VERIZON"
-      field :others, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "OTHERS"
+      field :carriers, -> { Pinnacle::Types::CarrierLaunchesCarriers }, optional: false, nullable: false
+      field :verification, -> { Pinnacle::Types::CarrierLaunchesVerification }, optional: false, nullable: false
     end
   end
 end

data/lib/pinnacle/types/carrier_launches_carriers.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Per-carrier launch status. Each carrier moves through
+    # `NOT_LAUNCHED` → `PENDING` → `LAUNCHED` as Pinnacle submits the
+    # agent for review and the carrier accepts it. The agent is only
+    # deliverable on a carrier once that carrier reports `LAUNCHED`.
+    class CarrierLaunchesCarriers < Internal::Types::Model
+      field :att, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "ATT"
+      field :tmobile, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "TMOBILE"
+      field :verizon, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "VERIZON"
+      field :others, -> { Pinnacle::Types::CarrierLaunchStatus }, optional: false, nullable: false, api_name: "OTHERS"
+    end
+  end
+end

data/lib/pinnacle/types/carrier_launches_verification.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # External verifier status. AEGIS (the U.S. carrier vetting
+    # authority used by AT&T, T-Mobile, and Verizon) and Google each
+    # send a verification email to the brand's contact address. Each
+    # verifier moves through `NOT_SENT` → `SENT` → `VERIFIED` once
+    # the brand replies and the verifier confirms ownership.
+    class CarrierLaunchesVerification < Internal::Types::Model
+      field :aegis, -> { Pinnacle::Types::VerificationStatus }, optional: false, nullable: false, api_name: "AEGIS"
+      field :google, -> { Pinnacle::Types::VerificationStatus }, optional: false, nullable: false, api_name: "GOOGLE"
+    end
+  end
+end

data/lib/pinnacle/types/checkbox_field.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Multi-select checkbox group when `options` is provided. If `options` is omitted the field renders as a single
+    # boolean checkbox.
+    class CheckboxField < Internal::Types::Model
+      field :options, -> { Internal::Types::Array[Pinnacle::Types::FormFieldOption] }, optional: true, nullable: false
+      field :min_selected, -> { Integer }, optional: true, nullable: false
+      field :max_selected, -> { Integer }, optional: true, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/color_field.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Native color picker. Submitted value is a 6-digit hex string like `#ff6b35`.
+    class ColorField < Internal::Types::Model; end
+  end
+end

data/lib/pinnacle/types/create_form_request.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    module CreateFormRequest
+      # CreateFormRequest is an alias for FormDefinition
+
+      # @option str [String]
+      #
+      # @return [untyped]
+      def self.load(str)
+        ::JSON.parse(str)
+      end
+
+      # @option value [untyped]
+      #
+      # @return [String]
+      def self.dump(value)
+        ::JSON.generate(value)
+      end
+    end
+  end
+end

data/lib/pinnacle/types/date_field.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Date picker. `min`/`max` accept `YYYY-MM-DD`.
+    class DateField < Internal::Types::Model
+      field :placeholder, -> { String }, optional: true, nullable: false
+      field :min, -> { String }, optional: true, nullable: false
+      field :max, -> { String }, optional: true, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/datetime_field.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Local-datetime picker. `min`/`max` accept ISO 8601 timestamps.
+    class DatetimeField < Internal::Types::Model
+      field :placeholder, -> { String }, optional: true, nullable: false
+      field :min, -> { String }, optional: true, nullable: false
+      field :max, -> { String }, optional: true, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/email_field.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Email input. Server rejects values that fail RFC 5322 validation.
+    class EmailField < Internal::Types::Model
+      field :placeholder, -> { String }, optional: true, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/field_base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Properties shared by every field variant. Not intended to be referenced directly — use a specific field type from
+    # `FormField`.
+    class FieldBase < Internal::Types::Model
+      field :key, -> { String }, optional: false, nullable: false
+      field :label, -> { String }, optional: false, nullable: false
+      field :required, -> { Internal::Types::Boolean }, optional: true, nullable: false
+      field :help_text, -> { String }, optional: true, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/form.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # A hosted form definition.
+    class Form < Internal::Types::Model
+      field :id, -> { String }, optional: false, nullable: false
+      field :url, -> { String }, optional: false, nullable: false
+      field :name, -> { String }, optional: false, nullable: true
+      field :description, -> { String }, optional: false, nullable: true
+      field :fields, -> { Internal::Types::Array[Pinnacle::Types::FormField] }, optional: false, nullable: false
+      field :can_update, -> { Internal::Types::Boolean }, optional: false, nullable: false
+      field :expires_at, -> { String }, optional: false, nullable: true
+      field :theme_override, -> { Pinnacle::Types::FormThemeOverride }, optional: false, nullable: true
+      field :submission_count, -> { Integer }, optional: false, nullable: false
+      field :last_submitted_at, -> { String }, optional: false, nullable: true
+      field :archived_at, -> { String }, optional: false, nullable: true
+      field :created_at, -> { String }, optional: false, nullable: false
+      field :updated_at, -> { String }, optional: false, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/form_background.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Background layer for the form page. Discriminated by `type`.
+    class FormBackground < Internal::Types::Model
+      extend Pinnacle::Internal::Types::Union
+
+      discriminant :type
+
+      member -> { Pinnacle::Types::FormBackgroundSolid }, key: "SOLID"
+      member -> { Pinnacle::Types::FormBackgroundGradient }, key: "GRADIENT"
+      member -> { Pinnacle::Types::FormBackgroundImage }, key: "IMAGE"
+      member -> { Pinnacle::Types::FormBackgroundPattern }, key: "PATTERN"
+    end
+  end
+end

data/lib/pinnacle/types/form_background_gradient.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Two-stop linear gradient. Supply separate light- and dark-mode gradients; the renderer picks based on
+    # `theme_mode`.
+    class FormBackgroundGradient < Internal::Types::Model
+      field :light, -> { Pinnacle::Types::FormGradient }, optional: false, nullable: false
+      field :dark, -> { Pinnacle::Types::FormGradient }, optional: false, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/form_background_image.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Image background. The image is tiled or scaled across the page with optional blur and dark tint overlay.
+    class FormBackgroundImage < Internal::Types::Model
+      field :url, -> { String }, optional: false, nullable: false
+      field :tint_opacity, -> { Integer }, optional: false, nullable: false
+      field :blur, -> { Internal::Types::Boolean }, optional: false, nullable: false
+      field :zoom, -> { Integer }, optional: false, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/form_background_pattern.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Subtle repeating SVG pattern tinted by the palette's foreground color.
+    class FormBackgroundPattern < Internal::Types::Model
+      field :preset, -> { Pinnacle::Types::FormBackgroundPatternPreset }, optional: false, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/form_background_pattern_preset.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    module FormBackgroundPatternPreset
+      extend Pinnacle::Internal::Types::Enum
+
+      NOISE = "noise"
+      DOTS = "dots"
+      MESH = "mesh"
+      GRID = "grid"
+      WAVES = "waves"
+      TOPO = "topo"
+    end
+  end
+end

data/lib/pinnacle/types/form_background_solid.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # No background effect — the form page is filled with a single flat color. The color itself isn't specified on this
+    # object; it's read from the sibling `colors` field on the same `theme_override` object (i.e.
+    # `theme_override.colors.light.background` in light mode, `theme_override.colors.dark.background` in dark mode). If
+    # you don't override `colors`, the color falls back to the one your team has configured in the [Pinnacle
+    # Dashboard](https://app.pinnacle.sh/dashboard/forms).
+    #
+    # Complete example — a POST `/forms` body that sets a white form in light mode and near-black in dark mode with no
+    # background effect:
+    #
+    # ```json
+    # {
+    #   "name": "Contact request",
+    #   "fields": [
+    #     { "type": "text", "key": "full_name", "label": "Full name", "required": true }
+    #   ],
+    #   "theme_override": {
+    #     "background": { "type": "solid" },
+    #     "colors": {
+    #       "light": { "background": "#ffffff" },
+    #       "dark":  { "background": "#0a0a0a" }
+    #     }
+    #   }
+    # }
+    # ```
+    #
+    # Pick `solid` when you want a clean one-color page with no gradient / image / pattern overlay. Use `gradient`,
+    # `image`, or `pattern` instead when you want something layered on top of the base color.
+    class FormBackgroundSolid < Internal::Types::Model; end
+  end
+end

data/lib/pinnacle/types/form_color_palette.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # Per-mode palette. All three colors are optional; any you omit fall back to the team default for that mode.
+    class FormColorPalette < Internal::Types::Model
+      field :primary, -> { String }, optional: true, nullable: false
+      field :background, -> { String }, optional: true, nullable: false
+      field :text, -> { String }, optional: true, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/form_definition.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # The minimum shape needed to create a form. Used by `POST /forms` and inline by `POST /forms/send`.
+    class FormDefinition < Internal::Types::Model
+      field :name, -> { String }, optional: true, nullable: false
+      field :description, -> { String }, optional: true, nullable: false
+      field :fields, -> { Internal::Types::Array[Pinnacle::Types::FormField] }, optional: false, nullable: false
+      field :can_update, -> { Internal::Types::Boolean }, optional: true, nullable: false
+      field :expires_at, -> { String }, optional: true, nullable: false
+      field :theme_override, -> { Pinnacle::Types::FormThemeOverride }, optional: true, nullable: false
+    end
+  end
+end

data/lib/pinnacle/types/form_field.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Types
+    # A single field definition inside a form. Discriminated by `type`.
+    class FormField < Internal::Types::Model
+      extend Pinnacle::Internal::Types::Union
+
+      discriminant :type
+
+      member -> { Pinnacle::Types::TextField }, key: "TEXT"
+      member -> { Pinnacle::Types::TextareaField }, key: "TEXTAREA"
+      member -> { Pinnacle::Types::AddressField }, key: "ADDRESS"
+      member -> { Pinnacle::Types::EmailField }, key: "EMAIL"
+      member -> { Pinnacle::Types::UrlField }, key: "URL"
+      member -> { Pinnacle::Types::PhoneField }, key: "PHONE"
+      member -> { Pinnacle::Types::NumberField }, key: "NUMBER"
+      member -> { Pinnacle::Types::RangeField }, key: "RANGE"
+      member -> { Pinnacle::Types::RatingField }, key: "RATING"
+      member -> { Pinnacle::Types::DateField }, key: "DATE"
+      member -> { Pinnacle::Types::TimeField }, key: "TIME"
+      member -> { Pinnacle::Types::DatetimeField }, key: "DATETIME"
+      member -> { Pinnacle::Types::ColorField }, key: "COLOR"
+      member -> { Pinnacle::Types::SelectField }, key: "SELECT"
+      member -> { Pinnacle::Types::RadioField }, key: "RADIO"
+      member -> { Pinnacle::Types::CheckboxField }, key: "CHECKBOX"
+    end
+  end
+end