docs(api): document provider settings.rate_limit [C-21732]

courier-java-core/src/main/kotlin/com/courier/models/providers/Provider.kt

@@ -68,7 +68,9 @@ private constructor(
     fun provider(): String = provider.getRequired("provider")
 
     /**
-     * Provider-specific settings (snake_case keys on the wire).
+     * Provider-specific settings (snake_case keys on the wire). `rate_limit` is this
+     * configuration's send rate limit, `{ "rate": number, "period": "second" | "minute" | "hour"
+     * }`, or null for no limit.
      *
      * @throws CourierInvalidDataException if the JSON field has an unexpected type or is
      *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
@@ -234,7 +236,11 @@ private constructor(
          */
         fun provider(provider: JsonField<String>) = apply { this.provider = provider }
 
-        /** Provider-specific settings (snake_case keys on the wire). */
+        /**
+         * Provider-specific settings (snake_case keys on the wire). `rate_limit` is this
+         * configuration's send rate limit, `{ "rate": number, "period": "second" | "minute" |
+         * "hour" }`, or null for no limit.
+         */
         fun settings(settings: Settings) = settings(JsonField.of(settings))
 
         /**
@@ -385,7 +391,11 @@ private constructor(
             (if (alias.asKnown().isPresent) 1 else 0) +
             (if (updated.asKnown().isPresent) 1 else 0)
 
-    /** Provider-specific settings (snake_case keys on the wire). */
+    /**
+     * Provider-specific settings (snake_case keys on the wire). `rate_limit` is this
+     * configuration's send rate limit, `{ "rate": number, "period": "second" | "minute" | "hour"
+     * }`, or null for no limit.
+     */
     class Settings
     @JsonCreator
     private constructor(

courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderCreateParams.kt

@@ -58,7 +58,15 @@ private constructor(
     /**
      * Provider-specific settings (snake_case keys). Defaults to an empty object when omitted. Use
      * the catalog endpoint to discover required fields for a given provider — omitting a required
-     * field returns a 400 validation error.
+     * field returns a 400 validation error. Set `rate_limit` to cap this configuration's send rate:
+     * `{ "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }`, e.g. `{
+     * "rate": 0.5, "period": "minute" }` for one send every 2 minutes. The interval between sends
+     * (`period` divided by `rate`) must be from 1 millisecond to 12 hours, otherwise the request
+     * returns a 400 `InvalidRateLimit` error. The limit applies per configuration and per
+     * environment (a test-environment configuration has its own limit). Sends above the rate are
+     * queued, not dropped, and changes take up to 60 seconds to apply. It has no effect on
+     * observability or CDP integrations, which do not send messages. Omit it or set it to null for
+     * no limit.
      *
      * @throws CourierInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -199,7 +207,15 @@ private constructor(
         /**
          * Provider-specific settings (snake_case keys). Defaults to an empty object when omitted.
          * Use the catalog endpoint to discover required fields for a given provider — omitting a
-         * required field returns a 400 validation error.
+         * required field returns a 400 validation error. Set `rate_limit` to cap this
+         * configuration's send rate: `{ "rate": <number greater than 0>, "period": "second" |
+         * "minute" | "hour" }`, e.g. `{ "rate": 0.5, "period": "minute" }` for one send every 2
+         * minutes. The interval between sends (`period` divided by `rate`) must be from 1
+         * millisecond to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error.
+         * The limit applies per configuration and per environment (a test-environment configuration
+         * has its own limit). Sends above the rate are queued, not dropped, and changes take up to
+         * 60 seconds to apply. It has no effect on observability or CDP integrations, which do not
+         * send messages. Omit it or set it to null for no limit.
          */
         fun settings(settings: Settings) = apply { body.settings(settings) }
 
@@ -418,7 +434,15 @@ private constructor(
         /**
          * Provider-specific settings (snake_case keys). Defaults to an empty object when omitted.
          * Use the catalog endpoint to discover required fields for a given provider — omitting a
-         * required field returns a 400 validation error.
+         * required field returns a 400 validation error. Set `rate_limit` to cap this
+         * configuration's send rate: `{ "rate": <number greater than 0>, "period": "second" |
+         * "minute" | "hour" }`, e.g. `{ "rate": 0.5, "period": "minute" }` for one send every 2
+         * minutes. The interval between sends (`period` divided by `rate`) must be from 1
+         * millisecond to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error.
+         * The limit applies per configuration and per environment (a test-environment configuration
+         * has its own limit). Sends above the rate are queued, not dropped, and changes take up to
+         * 60 seconds to apply. It has no effect on observability or CDP integrations, which do not
+         * send messages. Omit it or set it to null for no limit.
          *
          * @throws CourierInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -534,7 +558,16 @@ private constructor(
             /**
              * Provider-specific settings (snake_case keys). Defaults to an empty object when
              * omitted. Use the catalog endpoint to discover required fields for a given provider —
-             * omitting a required field returns a 400 validation error.
+             * omitting a required field returns a 400 validation error. Set `rate_limit` to cap
+             * this configuration's send rate: `{ "rate": <number greater than 0>, "period":
+             * "second" | "minute" | "hour" }`, e.g. `{ "rate": 0.5, "period": "minute" }` for one
+             * send every 2 minutes. The interval between sends (`period` divided by `rate`) must be
+             * from 1 millisecond to 12 hours, otherwise the request returns a 400
+             * `InvalidRateLimit` error. The limit applies per configuration and per environment (a
+             * test-environment configuration has its own limit). Sends above the rate are queued,
+             * not dropped, and changes take up to 60 seconds to apply. It has no effect on
+             * observability or CDP integrations, which do not send messages. Omit it or set it to
+             * null for no limit.
              */
             fun settings(settings: Settings) = settings(JsonField.of(settings))
 
@@ -670,7 +703,15 @@ private constructor(
     /**
      * Provider-specific settings (snake_case keys). Defaults to an empty object when omitted. Use
      * the catalog endpoint to discover required fields for a given provider — omitting a required
-     * field returns a 400 validation error.
+     * field returns a 400 validation error. Set `rate_limit` to cap this configuration's send rate:
+     * `{ "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }`, e.g. `{
+     * "rate": 0.5, "period": "minute" }` for one send every 2 minutes. The interval between sends
+     * (`period` divided by `rate`) must be from 1 millisecond to 12 hours, otherwise the request
+     * returns a 400 `InvalidRateLimit` error. The limit applies per configuration and per
+     * environment (a test-environment configuration has its own limit). Sends above the rate are
+     * queued, not dropped, and changes take up to 60 seconds to apply. It has no effect on
+     * observability or CDP integrations, which do not send messages. Omit it or set it to null for
+     * no limit.
      */
     class Settings
     @JsonCreator

courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderUpdateParams.kt

@@ -54,7 +54,16 @@ private constructor(
 
     /**
      * Provider-specific settings (snake_case keys). Replaces the full settings object — omitted
-     * settings fields are removed. Use the catalog endpoint to check required fields.
+     * settings fields are removed. Use the catalog endpoint to check required fields. Set
+     * `rate_limit` to cap this configuration's send rate: `{ "rate": <number greater than 0>,
+     * "period": "second" | "minute" | "hour" }`, e.g. `{ "rate": 0.5, "period": "minute" }` for one
+     * send every 2 minutes. The interval between sends (`period` divided by `rate`) must be from 1
+     * millisecond to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error. The
+     * limit applies per configuration and per environment (a test-environment configuration has its
+     * own limit). Sends above the rate are queued, not dropped, and changes take up to 60 seconds
+     * to apply. It has no effect on observability or CDP integrations, which do not send messages.
+     * Omitting `rate_limit` or setting it to null removes any existing limit, including one set in
+     * Studio.
      *
      * @throws CourierInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -180,7 +189,16 @@ private constructor(
 
         /**
          * Provider-specific settings (snake_case keys). Replaces the full settings object — omitted
-         * settings fields are removed. Use the catalog endpoint to check required fields.
+         * settings fields are removed. Use the catalog endpoint to check required fields. Set
+         * `rate_limit` to cap this configuration's send rate: `{ "rate": <number greater than 0>,
+         * "period": "second" | "minute" | "hour" }`, e.g. `{ "rate": 0.5, "period": "minute" }` for
+         * one send every 2 minutes. The interval between sends (`period` divided by `rate`) must be
+         * from 1 millisecond to 12 hours, otherwise the request returns a 400 `InvalidRateLimit`
+         * error. The limit applies per configuration and per environment (a test-environment
+         * configuration has its own limit). Sends above the rate are queued, not dropped, and
+         * changes take up to 60 seconds to apply. It has no effect on observability or CDP
+         * integrations, which do not send messages. Omitting `rate_limit` or setting it to null
+         * removes any existing limit, including one set in Studio.
          */
         fun settings(settings: Settings) = apply { body.settings(settings) }
 
@@ -402,7 +420,16 @@ private constructor(
 
         /**
          * Provider-specific settings (snake_case keys). Replaces the full settings object — omitted
-         * settings fields are removed. Use the catalog endpoint to check required fields.
+         * settings fields are removed. Use the catalog endpoint to check required fields. Set
+         * `rate_limit` to cap this configuration's send rate: `{ "rate": <number greater than 0>,
+         * "period": "second" | "minute" | "hour" }`, e.g. `{ "rate": 0.5, "period": "minute" }` for
+         * one send every 2 minutes. The interval between sends (`period` divided by `rate`) must be
+         * from 1 millisecond to 12 hours, otherwise the request returns a 400 `InvalidRateLimit`
+         * error. The limit applies per configuration and per environment (a test-environment
+         * configuration has its own limit). Sends above the rate are queued, not dropped, and
+         * changes take up to 60 seconds to apply. It has no effect on observability or CDP
+         * integrations, which do not send messages. Omitting `rate_limit` or setting it to null
+         * removes any existing limit, including one set in Studio.
          *
          * @throws CourierInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -518,7 +545,16 @@ private constructor(
             /**
              * Provider-specific settings (snake_case keys). Replaces the full settings object —
              * omitted settings fields are removed. Use the catalog endpoint to check required
-             * fields.
+             * fields. Set `rate_limit` to cap this configuration's send rate: `{ "rate": <number
+             * greater than 0>, "period": "second" | "minute" | "hour" }`, e.g. `{ "rate": 0.5,
+             * "period": "minute" }` for one send every 2 minutes. The interval between sends
+             * (`period` divided by `rate`) must be from 1 millisecond to 12 hours, otherwise the
+             * request returns a 400 `InvalidRateLimit` error. The limit applies per configuration
+             * and per environment (a test-environment configuration has its own limit). Sends above
+             * the rate are queued, not dropped, and changes take up to 60 seconds to apply. It has
+             * no effect on observability or CDP integrations, which do not send messages. Omitting
+             * `rate_limit` or setting it to null removes any existing limit, including one set in
+             * Studio.
              */
             fun settings(settings: Settings) = settings(JsonField.of(settings))
 
@@ -653,7 +689,16 @@ private constructor(
 
     /**
      * Provider-specific settings (snake_case keys). Replaces the full settings object — omitted
-     * settings fields are removed. Use the catalog endpoint to check required fields.
+     * settings fields are removed. Use the catalog endpoint to check required fields. Set
+     * `rate_limit` to cap this configuration's send rate: `{ "rate": <number greater than 0>,
+     * "period": "second" | "minute" | "hour" }`, e.g. `{ "rate": 0.5, "period": "minute" }` for one
+     * send every 2 minutes. The interval between sends (`period` divided by `rate`) must be from 1
+     * millisecond to 12 hours, otherwise the request returns a 400 `InvalidRateLimit` error. The
+     * limit applies per configuration and per environment (a test-environment configuration has its
+     * own limit). Sends above the rate are queued, not dropped, and changes take up to 60 seconds
+     * to apply. It has no effect on observability or CDP integrations, which do not send messages.
+     * Omitting `rate_limit` or setting it to null removes any existing limit, including one set in
+     * Studio.
      */
     class Settings
     @JsonCreator