trycourier 3.1.4 → 3.4.0.pre.alpha0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ef8a73dedc8e0e26aa02ee03adda892eda636512578a83e306551a9ded25f15
-  data.tar.gz: 498dae14ae276ac2fc3eb6c0abc3652239095ccb6c68328606f83364626388ad
+  metadata.gz: 10a685f0158dc46fd5971ae70795bcaad639c05ad1f1710af2a3f2699689e03e
+  data.tar.gz: 8acb94f1519df9a77c739ca6a4f268187464b4176f132042515d7d454bddd084
 SHA512:
-  metadata.gz: 58077fdf948937d1359f562fa7793d5dba44a9d075dc68b01e02eada43408f40ae67d8986941af280a288a1db6b522ea0c74e4d6662ddc28c3f8e35c2f498d9e
-  data.tar.gz: 1c908731530a06428cd6d5f2693d3f6717e0384f2bf968f6a2563ee2a038f7fd8928c11f7236e54e783c818055280de5c0fde0f4aa9e84e86d262f672bb4248f
+  metadata.gz: '0831fc393a836107629f2f6e17a756f1d1f58deaca215e76d8c98ddf3350b6ade4d8fe7f78b135ab0d25fd4c9dc766dbd93f1679c1a1142ed115379a30407cbd'
+  data.tar.gz: be4d4c2f845e04f56905f17f5174bef4d0fd88698f7d53431b7a1948a2a3a23824d486737a6dde521a8ea7cf859e776e54b42d557ed5ce2c87574d18455a24fa

data/.ignore

@@ -0,0 +1,2 @@
+rbi/*
+sig/*

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 3.4.0-alpha0 (2025-10-10)
+
+Full Changelog: [v0.0.1...v3.4.0-alpha0](https://github.com/trycourier/courier-ruby/compare/v0.0.1...v3.4.0-alpha0)
+
+### Features
+
+* **api:** manual updates ([051c3c4](https://github.com/trycourier/courier-ruby/commit/051c3c4722fa39896d01d0841f4989c91aa75c45))
+* **api:** manual updates ([ea5dfb3](https://github.com/trycourier/courier-ruby/commit/ea5dfb319688c23cc97da6a6ad80d4837bae04dd))
+* **api:** manual updates ([589a36f](https://github.com/trycourier/courier-ruby/commit/589a36f974d97fa73ecdf9a2a9b335492b15b203))
+* **api:** manual updates ([373bfde](https://github.com/trycourier/courier-ruby/commit/373bfde900f61ab7d70dcf775bd6aba16559d4df))
+* **api:** manual updates ([7c80f38](https://github.com/trycourier/courier-ruby/commit/7c80f3886fee9dc87253362a3eb51fe73cb44827))
+* **api:** manual updates ([f6681a9](https://github.com/trycourier/courier-ruby/commit/f6681a932e946bce954e2636f711694339d80471))
+* **api:** manual updates ([6a77929](https://github.com/trycourier/courier-ruby/commit/6a779292f8e2479621698d89a344466d95c97eab))
+* **api:** manual updates ([ab9922d](https://github.com/trycourier/courier-ruby/commit/ab9922d111846aebe424749ae0cb9668332e3e62))
+* **api:** manual updates ([4de89e5](https://github.com/trycourier/courier-ruby/commit/4de89e5fdad38358f42a1fec4835eda07247b57e))
+* **api:** manual updates ([babe4b8](https://github.com/trycourier/courier-ruby/commit/babe4b874fe7a4b5f8b306a5ebce7be0baf877e3))
+* **api:** manual updates ([91ad238](https://github.com/trycourier/courier-ruby/commit/91ad2389821d60def82ce67ee5f42f3a7f803f1c))
+* **api:** manual updates ([f80182f](https://github.com/trycourier/courier-ruby/commit/f80182f49b5abc44e758579d1ab9b475e1f41c95))
+* **api:** manual updates ([0d85b82](https://github.com/trycourier/courier-ruby/commit/0d85b8277f8b92d4f387298a7783cbcbf3c585a2))
+* **api:** manual updates ([8d639b8](https://github.com/trycourier/courier-ruby/commit/8d639b8acc654df6242511b035f04d1995298c0b))
+* **api:** manual updates ([2af24a7](https://github.com/trycourier/courier-ruby/commit/2af24a7f27da9496ebfb49a35549483bf8560e43))
+* **api:** manual updates ([221c2cd](https://github.com/trycourier/courier-ruby/commit/221c2cdeba247e19415c225a58869b0a742e82a1))
+* **api:** manual updates ([26c6626](https://github.com/trycourier/courier-ruby/commit/26c66263d5fcd8b10199bffcd4eda41a2b7595ed))
+* **api:** manual updates ([97e07ab](https://github.com/trycourier/courier-ruby/commit/97e07ab0a708eaaaf8e413128c09cb634082c141))
+* **api:** manual updates ([e8ed384](https://github.com/trycourier/courier-ruby/commit/e8ed384bcf0bc996e047b9489a13e0f3c5d12fb7))
+* **api:** manual updates ([e08aa78](https://github.com/trycourier/courier-ruby/commit/e08aa7845992968fcadf24969611c421dd03d81a))
+* **api:** manual updates ([06e1d8b](https://github.com/trycourier/courier-ruby/commit/06e1d8b7a7cf573fd5819c17b5d6201a1e408360))
+* **api:** manual updates ([8601f07](https://github.com/trycourier/courier-ruby/commit/8601f075e4e693560ab29f4690fea6128425652e))
+* **api:** manual updates ([d4899ce](https://github.com/trycourier/courier-ruby/commit/d4899cecd40d44295accc88b24b10ae9fac9d14d))
+* **api:** manual updates ([00a8012](https://github.com/trycourier/courier-ruby/commit/00a8012e858163fb45d62e44f657af3bda6550ed))
+* **api:** manual updates ([2977a88](https://github.com/trycourier/courier-ruby/commit/2977a881d647d04429db5135adc020cf50e13c27))
+* **api:** manual updates ([8a878a0](https://github.com/trycourier/courier-ruby/commit/8a878a0e7ea0b8cce0cd54e37f221ddb5ec204d4))
+* **api:** manual updates ([d5cc23f](https://github.com/trycourier/courier-ruby/commit/d5cc23f99b5306e48ef130e144bceb1aa57a7490))
+* **api:** manual updates ([1dd87c0](https://github.com/trycourier/courier-ruby/commit/1dd87c099c7df921bc93c36005d8cde767a8687e))
+* **api:** manual updates ([9b2b74a](https://github.com/trycourier/courier-ruby/commit/9b2b74a6c40c82333762e187f002bc021942f064))
+* **api:** manual updates ([d81fc71](https://github.com/trycourier/courier-ruby/commit/d81fc71f013ad0fb7701b73ca7ed4a9843c812f4))
+* **api:** manual updates ([f358b3d](https://github.com/trycourier/courier-ruby/commit/f358b3db2d81dcfd0906f0f66511588766292c12))
+* Examples and ref polish ([3987809](https://github.com/trycourier/courier-ruby/commit/3987809dc0da164ca687fc8d6b2870842c0836f4))
+* Model sync ([7d005d6](https://github.com/trycourier/courier-ruby/commit/7d005d69c8082e43e28bf04c43455d193c110543))
+* Polish and Kick of Java Kit Gen ([2e136c1](https://github.com/trycourier/courier-ruby/commit/2e136c1bd2e9d407d8289a39f5246f7d4c1c9174))
+* Template Id ([24598ca](https://github.com/trycourier/courier-ruby/commit/24598cabff382ebc414e8e2f1c815709ebdd7caf))
+* Test Github Action ([5b988c5](https://github.com/trycourier/courier-ruby/commit/5b988c5fb80b9684ae6989361952077e90df366b))
+* Test stainless open action ([7d264c0](https://github.com/trycourier/courier-ruby/commit/7d264c0652b42286d5b3e9666c00f716e030c451))
+
+
+### Chores
+
+* configure new SDK language ([29f56f6](https://github.com/trycourier/courier-ruby/commit/29f56f69dd0a1ce4e4e894ae1432bda1da07fea1))
+* ignore linter error for tests having large collections ([59d9b7f](https://github.com/trycourier/courier-ruby/commit/59d9b7f9987c061850254e99c3713b2abb39662f))
+* update SDK settings ([0f6c8ef](https://github.com/trycourier/courier-ruby/commit/0f6c8ef4fb11a6127a57e16bbd07a547ec458cef))
+* update SDK settings ([021c76b](https://github.com/trycourier/courier-ruby/commit/021c76ba9fdedfe90ce34c90889008dff19f9df0))

data/README.md

@@ -0,0 +1,257 @@
+# Courier Ruby API library
+
+The Courier Ruby library provides convenient access to the Courier REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/trycourier/courier-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
+
+It is generated with [Stainless](https://www.stainless.com/).
+
+## Documentation
+
+Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/trycourier).
+
+## Installation
+
+To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
+
+<!-- x-release-please-start-version -->
+
+```ruby
+gem "trycourier", "~> 3.4.0.pre.alpha0"
+```
+
+<!-- x-release-please-end -->
+
+## Usage
+
+```ruby
+require "bundler/setup"
+require "trycourier"
+
+courier = Trycourier::Client.new(
+  api_key: ENV["COURIER_API_KEY"] # This is the default and can be omitted
+)
+
+response = courier.send_.message(
+  message: {to: {user_id: "your_user_id"}, template: "your_template", data: {foo: "bar"}}
+)
+
+puts(response.requestId)
+```
+
+### Handling errors
+
+When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Trycourier::Errors::APIError` will be thrown:
+
+```ruby
+begin
+  send_ = courier.send_.message(
+    message: {to: {user_id: "your_user_id"}, template: "your_template", data: {foo: "bar"}}
+  )
+rescue Trycourier::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue Trycourier::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue Trycourier::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
+end
+```
+
+Error codes are as follows:
+
+| Cause            | Error Type                 |
+| ---------------- | -------------------------- |
+| HTTP 400         | `BadRequestError`          |
+| HTTP 401         | `AuthenticationError`      |
+| HTTP 403         | `PermissionDeniedError`    |
+| HTTP 404         | `NotFoundError`            |
+| HTTP 409         | `ConflictError`            |
+| HTTP 422         | `UnprocessableEntityError` |
+| HTTP 429         | `RateLimitError`           |
+| HTTP >= 500      | `InternalServerError`      |
+| Other HTTP error | `APIStatusError`           |
+| Timeout          | `APITimeoutError`          |
+| Network error    | `APIConnectionError`       |
+
+### Retries
+
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
+
+You can use the `max_retries` option to configure or disable this:
+
+```ruby
+# Configure the default for all requests:
+courier = Trycourier::Client.new(
+  max_retries: 0 # default is 2
+)
+
+# Or, configure per-request:
+courier.send_.message(
+  message: {to: {user_id: "your_user_id"}, template: "your_template", data: {foo: "bar"}},
+  request_options: {max_retries: 5}
+)
+```
+
+### Timeouts
+
+By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
+
+```ruby
+# Configure the default for all requests:
+courier = Trycourier::Client.new(
+  timeout: nil # default is 60
+)
+
+# Or, configure per-request:
+courier.send_.message(
+  message: {to: {user_id: "your_user_id"}, template: "your_template", data: {foo: "bar"}},
+  request_options: {timeout: 5}
+)
+```
+
+On timeout, `Trycourier::Errors::APITimeoutError` is raised.
+
+Note that requests that time out are retried by default.
+
+## Advanced concepts
+
+### BaseModel
+
+All parameter and response objects inherit from `Trycourier::Internal::Type::BaseModel`, which provides several conveniences, including:
+
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
+
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
+
+3. Both instances and the classes themselves can be pretty-printed.
+
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
+
+### Making custom or undocumented requests
+
+#### Undocumented properties
+
+You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
+
+Note: the `extra_` parameters of the same name overrides the documented parameters.
+
+```ruby
+response =
+  courier.send_.message(
+    message: {to: {user_id: "your_user_id"}, template: "your_template", data: {foo: "bar"}},
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
+    }
+  )
+
+puts(response[:my_undocumented_property])
+```
+
+#### Undocumented request params
+
+If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.
+
+#### Undocumented endpoints
+
+To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
+
+```ruby
+response = client.request(
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"hello": "world"}
+)
+```
+
+### Concurrency & connection pooling
+
+The `Trycourier::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
+
+Each instance of `Trycourier::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
+
+When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
+
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
+
+## Sorbet
+
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
+
+You can provide typesafe request parameters like so:
+
+```ruby
+courier.send_.message(
+  message: Trycourier::SendMessageParams::Message.new(
+    to: Trycourier::UserRecipient.new(user_id: "your_user_id"),
+    template: "your_template",
+    data: {foo: "bar"}
+  )
+)
+```
+
+Or, equivalently:
+
+```ruby
+# Hashes work, but are not typesafe:
+courier.send_.message(
+  message: {to: {user_id: "your_user_id"}, template: "your_template", data: {foo: "bar"}}
+)
+
+# You can also splat a full Params class:
+params = Trycourier::SendMessageParams.new(
+  message: Trycourier::SendMessageParams::Message.new(
+    to: Trycourier::UserRecipient.new(user_id: "your_user_id"),
+    template: "your_template",
+    data: {foo: "bar"}
+  )
+)
+courier.send_.message(**params)
+```
+
+### Enums
+
+Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
+
+```ruby
+# :OPTED_OUT
+puts(Trycourier::SubscriptionTopicNew::Status::OPTED_OUT)
+
+# Revealed type: `T.all(Trycourier::SubscriptionTopicNew::Status, Symbol)`
+T.reveal_type(Trycourier::SubscriptionTopicNew::Status::OPTED_OUT)
+```
+
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
+
+```ruby
+# Using the enum constants preserves the tagged type information:
+courier.tenants.default_preferences.items.update(
+  status: Trycourier::SubscriptionTopicNew::Status::OPTED_OUT,
+  # …
+)
+
+# Literal values are also permissible:
+courier.tenants.default_preferences.items.update(
+  status: :OPTED_OUT,
+  # …
+)
+```
+
+## Versioning
+
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
+
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
+
+## Requirements
+
+Ruby 3.2.0 or higher.
+
+## Contributing
+
+See [the contributing documentation](https://github.com/trycourier/courier-ruby/tree/main/CONTRIBUTING.md).

data/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Reporting Security Issues
+
+This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
+
+To report a security issue, please contact the Stainless team at security@stainless.com.
+
+## Responsible Disclosure
+
+We appreciate the efforts of security researchers and individuals who help us maintain the security of
+SDKs we generate. If you believe you have found a security vulnerability, please adhere to responsible
+disclosure practices by allowing us a reasonable amount of time to investigate and address the issue
+before making any information public.
+
+## Reporting Non-SDK Related Security Issues
+
+If you encounter security issues that are not directly related to SDKs but pertain to the services
+or products provided by Courier, please follow the respective company's security reporting guidelines.
+
+---
+
+Thank you for helping us keep the SDKs and systems they interact with secure.

data/lib/trycourier/client.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Trycourier
+  class Client < Trycourier::Internal::Transport::BaseClient
+    # Default max number of retries to attempt after a failed retryable request.
+    DEFAULT_MAX_RETRIES = 2
+
+    # Default per-request timeout.
+    DEFAULT_TIMEOUT_IN_SECONDS = 60.0
+
+    # Default initial retry delay in seconds.
+    # Overall delay is calculated using exponential backoff + jitter.
+    DEFAULT_INITIAL_RETRY_DELAY = 0.5
+
+    # Default max retry delay in seconds.
+    DEFAULT_MAX_RETRY_DELAY = 8.0
+
+    # @return [String]
+    attr_reader :api_key
+
+    # @return [Trycourier::Resources::Send]
+    attr_reader :send_
+
+    # @return [Trycourier::Resources::Audiences]
+    attr_reader :audiences
+
+    # @return [Trycourier::Resources::AuditEvents]
+    attr_reader :audit_events
+
+    # @return [Trycourier::Resources::Auth]
+    attr_reader :auth
+
+    # @return [Trycourier::Resources::Automations]
+    attr_reader :automations
+
+    # @return [Trycourier::Resources::Brands]
+    attr_reader :brands
+
+    # @return [Trycourier::Resources::Bulk]
+    attr_reader :bulk
+
+    # @return [Trycourier::Resources::Inbound]
+    attr_reader :inbound
+
+    # @return [Trycourier::Resources::Lists]
+    attr_reader :lists
+
+    # @return [Trycourier::Resources::Messages]
+    attr_reader :messages
+
+    # @return [Trycourier::Resources::Requests]
+    attr_reader :requests
+
+    # @return [Trycourier::Resources::Notifications]
+    attr_reader :notifications
+
+    # @return [Trycourier::Resources::Profiles]
+    attr_reader :profiles
+
+    # @return [Trycourier::Resources::Tenants]
+    attr_reader :tenants
+
+    # @return [Trycourier::Resources::Translations]
+    attr_reader :translations
+
+    # @return [Trycourier::Resources::Users]
+    attr_reader :users
+
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def auth_headers
+      return {} if @api_key.nil?
+
+      {"authorization" => "Bearer #{@api_key}"}
+    end
+
+    # Creates and returns a new client for interacting with the API.
+    #
+    # @param api_key [String, nil] Defaults to `ENV["COURIER_API_KEY"]`
+    #
+    # @param base_url [String, nil] Override the default base URL for the API, e.g.,
+    # `"https://api.example.com/v2/"`. Defaults to `ENV["COURIER_BASE_URL"]`
+    #
+    # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
+    #
+    # @param timeout [Float]
+    #
+    # @param initial_retry_delay [Float]
+    #
+    # @param max_retry_delay [Float]
+    def initialize(
+      api_key: ENV["COURIER_API_KEY"],
+      base_url: ENV["COURIER_BASE_URL"],
+      max_retries: self.class::DEFAULT_MAX_RETRIES,
+      timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
+    )
+      base_url ||= "https://api.courier.com"
+
+      if api_key.nil?
+        raise ArgumentError.new("api_key is required, and can be set via environ: \"COURIER_API_KEY\"")
+      end
+
+      @api_key = api_key.to_s
+
+      super(
+        base_url: base_url,
+        timeout: timeout,
+        max_retries: max_retries,
+        initial_retry_delay: initial_retry_delay,
+        max_retry_delay: max_retry_delay
+      )
+
+      @send_ = Trycourier::Resources::Send.new(client: self)
+      @audiences = Trycourier::Resources::Audiences.new(client: self)
+      @audit_events = Trycourier::Resources::AuditEvents.new(client: self)
+      @auth = Trycourier::Resources::Auth.new(client: self)
+      @automations = Trycourier::Resources::Automations.new(client: self)
+      @brands = Trycourier::Resources::Brands.new(client: self)
+      @bulk = Trycourier::Resources::Bulk.new(client: self)
+      @inbound = Trycourier::Resources::Inbound.new(client: self)
+      @lists = Trycourier::Resources::Lists.new(client: self)
+      @messages = Trycourier::Resources::Messages.new(client: self)
+      @requests = Trycourier::Resources::Requests.new(client: self)
+      @notifications = Trycourier::Resources::Notifications.new(client: self)
+      @profiles = Trycourier::Resources::Profiles.new(client: self)
+      @tenants = Trycourier::Resources::Tenants.new(client: self)
+      @translations = Trycourier::Resources::Translations.new(client: self)
+      @users = Trycourier::Resources::Users.new(client: self)
+    end
+  end
+end