diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 00000000..bd8e2619
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,23 @@
+# syntax=docker/dockerfile:1
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ libxkbcommon0 \
+ ca-certificates \
+ ca-certificates-java \
+ make \
+ curl \
+ git \
+ openjdk-17-jdk-headless \
+ unzip \
+ libc++1 \
+ vim \
+ && apt-get clean autoclean
+
+# Ensure UTF-8 encoding
+ENV LANG=C.UTF-8
+ENV LC_ALL=C.UTF-8
+
+WORKDIR /workspace
+
+COPY . /workspace
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000..d55fc4d6
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,20 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/debian
+{
+ "name": "Debian",
+ "build": {
+ "dockerfile": "Dockerfile"
+ }
+
+ // Features to add to the dev container. More info: https://containers.dev/features.
+ // "features": {},
+
+ // Use 'forwardPorts' to make a list of ports inside the container available locally.
+ // "forwardPorts": [],
+
+ // Configure tool-specific properties.
+ // "customizations": {},
+
+ // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+ // "remoteUser": "root"
+}
diff --git a/.fernignore b/.fernignore
deleted file mode 100644
index 793636f0..00000000
--- a/.fernignore
+++ /dev/null
@@ -1,4 +0,0 @@
-# Specify files that shouldn't be modified by Fern
-
-LICENSE
-README.md
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 00000000..022b8414
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,5 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# These are explicitly windows files and should use crlf
+*.bat text eol=crlf
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2e52af1f..f668ddf3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,65 +1,85 @@
-name: ci
-
-on: [push]
+name: CI
+on:
+ push:
+ branches-ignore:
+ - 'generated'
+ - 'codegen/**'
+ - 'integrated/**'
+ - 'stl-preview-head/**'
+ - 'stl-preview-base/**'
+ pull_request:
+ branches-ignore:
+ - 'stl-preview-head/**'
+ - 'stl-preview-base/**'
jobs:
- compile:
- runs-on: ubuntu-latest
+ lint:
+ timeout-minutes: 15
+ name: lint
+ runs-on: ${{ github.repository == 'stainless-sdks/courier-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+ if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
steps:
- - name: Checkout repo
- uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- name: Set up Java
- id: setup-jre
- uses: actions/setup-java@v1
+ uses: actions/setup-java@v4
with:
- java-version: "11"
- architecture: x64
+ distribution: temurin
+ java-version: |
+ 8
+ 21
+ cache: gradle
- - name: Compile
- run: ./gradlew compileJava
+ - name: Set up Gradle
+ uses: gradle/actions/setup-gradle@v4
+
+ - name: Run lints
+ run: ./scripts/lint
+
+ build:
+ timeout-minutes: 15
+ name: build
+ runs-on: ${{ github.repository == 'stainless-sdks/courier-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+ if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
- test:
- needs: [ compile ]
- runs-on: ubuntu-latest
steps:
- - name: Checkout repo
- uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- name: Set up Java
- id: setup-jre
- uses: actions/setup-java@v1
+ uses: actions/setup-java@v4
with:
- java-version: "11"
- architecture: x64
+ distribution: temurin
+ java-version: |
+ 8
+ 21
+ cache: gradle
- - name: Test
- run: ./gradlew test
- publish:
- needs: [ compile, test ]
- if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
- runs-on: ubuntu-latest
+ - name: Set up Gradle
+ uses: gradle/actions/setup-gradle@v4
+ - name: Build SDK
+ run: ./scripts/build
+
+ test:
+ timeout-minutes: 15
+ name: test
+ runs-on: ${{ github.repository == 'stainless-sdks/courier-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+ if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
steps:
- - name: Checkout repo
- uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- name: Set up Java
- id: setup-jre
- uses: actions/setup-java@v1
+ uses: actions/setup-java@v4
with:
- java-version: "11"
- architecture: x64
+ distribution: temurin
+ java-version: |
+ 8
+ 21
+ cache: gradle
+
+ - name: Set up Gradle
+ uses: gradle/gradle-build-action@v2
- - name: Publish to maven
- run: |
- ./.publish/prepare.sh
- ./gradlew publish
- env:
- MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
- MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
- MAVEN_PUBLISH_REGISTRY_URL: "https://oss.sonatype.org/service/local/staging/deploy/maven2/"
- MAVEN_SIGNATURE_KID: ${{ secrets.MAVEN_SIGNATURE_KID }}
- MAVEN_SIGNATURE_SECRET_KEY: ${{ secrets.MAVEN_SIGNATURE_SECRET_KEY }}
- MAVEN_SIGNATURE_PASSWORD: ${{ secrets.MAVEN_SIGNATURE_PASSWORD }}
+ - name: Run tests
+ run: ./scripts/test
diff --git a/.github/workflows/publish-sonatype.yml b/.github/workflows/publish-sonatype.yml
new file mode 100644
index 00000000..bb1398a4
--- /dev/null
+++ b/.github/workflows/publish-sonatype.yml
@@ -0,0 +1,41 @@
+# This workflow is triggered when a GitHub release is created.
+# It can also be run manually to re-publish to Sonatype in case it failed for some reason.
+# You can run this workflow by navigating to https://www.github.com/trycourier/courier-java/actions/workflows/publish-sonatype.yml
+name: Publish Sonatype
+on:
+ workflow_dispatch:
+
+ release:
+ types: [published]
+
+jobs:
+ publish:
+ name: publish
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Java
+ uses: actions/setup-java@v4
+ with:
+ distribution: temurin
+ java-version: |
+ 8
+ 21
+ cache: gradle
+
+ - name: Set up Gradle
+ uses: gradle/gradle-build-action@v2
+
+ - name: Publish to Sonatype
+ run: |-
+ export -- GPG_SIGNING_KEY_ID
+ printenv -- GPG_SIGNING_KEY | gpg --batch --passphrase-fd 3 --import 3<<< "$GPG_SIGNING_PASSWORD"
+ GPG_SIGNING_KEY_ID="$(gpg --with-colons --list-keys | awk -F : -- '/^pub:/ { getline; print "0x" substr($10, length($10) - 7) }')"
+ ./gradlew publish --no-configuration-cache
+ env:
+ SONATYPE_USERNAME: ${{ secrets.COURIER_SONATYPE_USERNAME || secrets.SONATYPE_USERNAME }}
+ SONATYPE_PASSWORD: ${{ secrets.COURIER_SONATYPE_PASSWORD || secrets.SONATYPE_PASSWORD }}
+ GPG_SIGNING_KEY: ${{ secrets.COURIER_SONATYPE_GPG_SIGNING_KEY || secrets.GPG_SIGNING_KEY }}
+ GPG_SIGNING_PASSWORD: ${{ secrets.COURIER_SONATYPE_GPG_SIGNING_PASSWORD || secrets.GPG_SIGNING_PASSWORD }}
\ No newline at end of file
diff --git a/.github/workflows/release-doctor.yml b/.github/workflows/release-doctor.yml
new file mode 100644
index 00000000..ba006aee
--- /dev/null
+++ b/.github/workflows/release-doctor.yml
@@ -0,0 +1,24 @@
+name: Release Doctor
+on:
+ pull_request:
+ branches:
+ - main
+ workflow_dispatch:
+
+jobs:
+ release_doctor:
+ name: release doctor
+ runs-on: ubuntu-latest
+ if: github.repository == 'trycourier/courier-java' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Check release environment
+ run: |
+ bash ./bin/check-release-environment
+ env:
+ SONATYPE_USERNAME: ${{ secrets.COURIER_SONATYPE_USERNAME || secrets.SONATYPE_USERNAME }}
+ SONATYPE_PASSWORD: ${{ secrets.COURIER_SONATYPE_PASSWORD || secrets.SONATYPE_PASSWORD }}
+ GPG_SIGNING_KEY: ${{ secrets.COURIER_SONATYPE_GPG_SIGNING_KEY || secrets.GPG_SIGNING_KEY }}
+ GPG_SIGNING_PASSWORD: ${{ secrets.COURIER_SONATYPE_GPG_SIGNING_PASSWORD || secrets.GPG_SIGNING_PASSWORD }}
diff --git a/.gitignore b/.gitignore
index d4199abc..b1346e6d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,24 +1,7 @@
-*.class
-.project
+.prism.log
.gradle
-?
-.classpath
-.checkstyle
-.settings
-.node
-build
-
-# IntelliJ
-*.iml
-*.ipr
-*.iws
-.idea/
-out/
-
-# Eclipse/IntelliJ APT
-generated_src/
-generated_testSrc/
-generated/
-
-bin
-build
\ No newline at end of file
+.idea
+.kotlin
+build/
+codegen.log
+kls_database.db
diff --git a/.publish/prepare.sh b/.publish/prepare.sh
deleted file mode 100755
index df3948e3..00000000
--- a/.publish/prepare.sh
+++ /dev/null
@@ -1,8 +0,0 @@
-# Write key ring file
-echo "$MAVEN_SIGNATURE_SECRET_KEY" > armored_key.asc
-gpg -o publish_key.gpg --dearmor armored_key.asc
-
-# Generate gradle.properties file
-echo "signing.keyId=$MAVEN_SIGNATURE_KID" > gradle.properties
-echo "signing.secretKeyRingFile=publish_key.gpg" >> gradle.properties
-echo "signing.password=$MAVEN_SIGNATURE_PASSWORD" >> gradle.properties
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
new file mode 100644
index 00000000..3d2ac0bd
--- /dev/null
+++ b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+ ".": "0.1.0"
+}
\ No newline at end of file
diff --git a/.stats.yml b/.stats.yml
new file mode 100644
index 00000000..ed4a28c3
--- /dev/null
+++ b/.stats.yml
@@ -0,0 +1,4 @@
+configured_endpoints: 77
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier%2Fcourier-dac3180af01aad486854bd76602df9cd66d2c245baa2bddf60741d962dc5aa38.yml
+openapi_spec_hash: 2ba7c45b6a49a540a97b6a3336547cd4
+config_hash: 61ff8407ac3b017189b34dfe19b0d230
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..d5f28fd3
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.1.0 (2025-10-07)
+
+Full Changelog: [v0.0.1...v0.1.0](https://github.com/trycourier/courier-java/compare/v0.0.1...v0.1.0)
+
+### Features
+
+* **api:** manual updates ([51e1a35](https://github.com/trycourier/courier-java/commit/51e1a35ffcee9de2e8f8eb6b6e5ee443ba3cc1e3))
+* **api:** manual updates ([25ea9c2](https://github.com/trycourier/courier-java/commit/25ea9c20e06aaf842128758a136bcf961dcdc707))
+* **api:** manual updates ([61a87f9](https://github.com/trycourier/courier-java/commit/61a87f9d18bb355e008a69ab86c578d2763fddcc))
+* **api:** manual updates ([822e2a4](https://github.com/trycourier/courier-java/commit/822e2a4a7d93bdc32bfc2c92bd0cc1ac4b3ff359))
+* **api:** manual updates ([6bb1fba](https://github.com/trycourier/courier-java/commit/6bb1fbabc235d3cc1eb7489919bbb71b42bc22e9))
+* **api:** manual updates ([ead7d7c](https://github.com/trycourier/courier-java/commit/ead7d7cbf54c37a6aed22496051334693aa647ea))
+* **api:** manual updates ([e5bfbdb](https://github.com/trycourier/courier-java/commit/e5bfbdb1174fafbc1852694c138e364a98010ef3))
+* **api:** manual updates ([0435076](https://github.com/trycourier/courier-java/commit/043507613239e61b8173032071dd91f3b378c514))
+* **api:** manual updates ([e6ed828](https://github.com/trycourier/courier-java/commit/e6ed82846b54dea4c15295f1df79439dca3c4875))
+* **api:** manual updates ([0ec4d93](https://github.com/trycourier/courier-java/commit/0ec4d9354b7a702a83e9d305ea8a493eda3af820))
+* **api:** manual updates ([70aa287](https://github.com/trycourier/courier-java/commit/70aa2874518fd8f48e5cc8927b7abcea60787b7c))
+* **api:** manual updates ([998a0c1](https://github.com/trycourier/courier-java/commit/998a0c13140b88e4fba9fbd2374e07b3ec6a4849))
+* **api:** manual updates ([1d5dae3](https://github.com/trycourier/courier-java/commit/1d5dae306c780129e17111dae95b55bc600ad6e9))
+* **api:** manual updates ([26e335a](https://github.com/trycourier/courier-java/commit/26e335a72dc4aebf9c3b71f440f317ce4409371c))
+* **api:** manual updates ([6b9f529](https://github.com/trycourier/courier-java/commit/6b9f5296179dccc64931dd2afe8802cf06b69873))
+* **api:** manual updates ([2f68cbe](https://github.com/trycourier/courier-java/commit/2f68cbe54d8ed9f6ae5dc5c060e3067131acf3fb))
+* **api:** manual updates ([33a23f3](https://github.com/trycourier/courier-java/commit/33a23f3e6c64100af51e328215bc7d2a93fef331))
+* **api:** manual updates ([5c5e618](https://github.com/trycourier/courier-java/commit/5c5e61819a03f950fc01468e21f1aa58b3f9a49a))
+* **api:** manual updates ([1a3eab1](https://github.com/trycourier/courier-java/commit/1a3eab10a8b1eba2ed8bbdd82dffb81efae0155f))
+* **api:** manual updates ([e4986bc](https://github.com/trycourier/courier-java/commit/e4986bcd194638319398f2375e0a5304cbda49dd))
+* **api:** manual updates ([ab3ef5d](https://github.com/trycourier/courier-java/commit/ab3ef5d4292e846a80b39ae7c608305830637f64))
+
+
+### Chores
+
+* sync repo ([166f09d](https://github.com/trycourier/courier-java/commit/166f09d23f53cda5b63b60a9a785bc9e2e430fb7))
+* update SDK settings ([d4cde45](https://github.com/trycourier/courier-java/commit/d4cde450dc82626223aee050c5c848f70fe79382))
diff --git a/LICENSE b/LICENSE
index d82d2ea7..efaa7fe8 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2020 Courier
-
-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.
\ No newline at end of file
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2025 Courier
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/README.md b/README.md
index 60ee7d22..8d746006 100644
--- a/README.md
+++ b/README.md
@@ -1,149 +1,669 @@
-# Courier Java Library
+# Courier Java API Library
-[](https://central.sonatype.com/artifact/com.courier/courier-java)
-[](https://buildwithfern.com/?utm_source=trycourier/courier-java/readme)
+
-This is the official Java library for sending notifications with the [Courier](https://courier.com) REST API.
+[](https://central.sonatype.com/artifact/com.courier.api/courier-java/0.1.0)
+[](https://javadoc.io/doc/com.courier.api/courier-java/0.1.0)
-## Documentation
+
-For a full description of request and response payloads and properties, please see the
-[official Courier API docs](https://www.courier.com/docs/reference/).
+The Courier Java SDK provides convenient access to the Courier REST API from applications written in Java.
-## Requirements
+It is generated with [Stainless](https://www.stainless.com/).
+
+
-This library requires Java 11+.
+Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.courier.api/courier-java/0.1.0).
+
+
## Installation
-### Gradle
+
-Add the dependency in your `build.gradle`:
+### Gradle
-```groovy
-dependencies {
- implementation 'com.courier:courier-java:x.x.x'
-}
+```kotlin
+implementation("com.courier.api:courier-java:0.1.0")
```
### Maven
-Add the dependency in your `pom.xml`:
-
```xml
- com.courier
- courier-java
- 0.x.x
+ com.courier.api
+ courier-java
+ 0.1.0
```
+
+
+## Requirements
+
+This library requires Java 8 or later.
+
## Usage
-Below is an example of how to instantiate the Courier client
-and send a message.
```java
-import com.courier.api.Courier;
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+import com.courier.api.core.JsonValue;
+import com.courier.api.models.bulk.UserRecipient;
+import com.courier.api.models.send.SendMessageParams;
+import com.courier.api.models.send.SendMessageResponse;
+
+// Configures using the `courier.apiKey` and `courier.baseUrl` system properties
+// Or configures using the `COURIER_API_KEY` and `COURIER_BASE_URL` environment variables
+CourierClient client = CourierOkHttpClient.fromEnv();
+
+SendMessageParams params = SendMessageParams.builder()
+ .message(SendMessageParams.Message.builder()
+ .to(UserRecipient.builder()
+ .userId("your_user_id")
+ .build())
+ .data(SendMessageParams.Message.Data.builder()
+ .putAdditionalProperty("foo", JsonValue.from("bar"))
+ .build())
+ .build())
+ .build();
+SendMessageResponse response = client.send().message(params);
+```
+
+## Client configuration
+
+Configure the client using system properties or environment variables:
+
+```java
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+
+// Configures using the `courier.apiKey` and `courier.baseUrl` system properties
+// Or configures using the `COURIER_API_KEY` and `COURIER_BASE_URL` environment variables
+CourierClient client = CourierOkHttpClient.fromEnv();
+```
+
+Or manually:
+
+```java
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+
+CourierClient client = CourierOkHttpClient.builder()
+ .apiKey("My API Key")
+ .build();
+```
+
+Or using a combination of the two approaches:
+
+```java
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+
+CourierClient client = CourierOkHttpClient.builder()
+ // Configures using the `courier.apiKey` and `courier.baseUrl` system properties
+ // Or configures using the `COURIER_API_KEY` and `COURIER_BASE_URL` environment variables
+ .fromEnv()
+ .apiKey("My API Key")
+ .build();
+```
+
+See this table for the available options:
+
+| Setter | System property | Environment variable | Required | Default value |
+| --------- | ----------------- | -------------------- | -------- | --------------------------- |
+| `apiKey` | `courier.apiKey` | `COURIER_API_KEY` | true | - |
+| `baseUrl` | `courier.baseUrl` | `COURIER_BASE_URL` | true | `"https://api.courier.com"` |
+
+System properties take precedence over environment variables.
+
+> [!TIP]
+> Don't create more than one client in the same application. Each client has a connection pool and
+> thread pools, which are more efficient to share between requests.
+
+### Modifying configuration
+
+To temporarily use a modified client configuration, while reusing the same connection and thread pools, call `withOptions()` on any client or service:
+
+```java
+import com.courier.api.client.CourierClient;
+
+CourierClient clientWithOptions = client.withOptions(optionsBuilder -> {
+ optionsBuilder.baseUrl("https://example.com");
+ optionsBuilder.maxRetries(42);
+});
+```
+
+The `withOptions()` method does not affect the original client or service.
+
+## Requests and responses
+
+To send a request to the Courier API, build an instance of some `Params` class and pass it to the corresponding client method. When the response is received, it will be deserialized into an instance of a Java class.
+
+For example, `client.send().message(...)` should be called with an instance of `SendMessageParams`, and it will return an instance of `SendMessageResponse`.
+
+## Immutability
+
+Each class in the SDK has an associated [builder](https://blogs.oracle.com/javamagazine/post/exploring-joshua-blochs-builder-design-pattern-in-java) or factory method for constructing it.
+
+Each class is [immutable](https://docs.oracle.com/javase/tutorial/essential/concurrency/immutable.html) once constructed. If the class has an associated builder, then it has a `toBuilder()` method, which can be used to convert it back to a builder for making a modified copy.
+
+Because each class is immutable, builder modification will _never_ affect already built class instances.
+
+## Asynchronous execution
+
+The default client is synchronous. To switch to asynchronous execution, call the `async()` method:
+
+```java
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+import com.courier.api.core.JsonValue;
+import com.courier.api.models.bulk.UserRecipient;
+import com.courier.api.models.send.SendMessageParams;
+import com.courier.api.models.send.SendMessageResponse;
+import java.util.concurrent.CompletableFuture;
+
+// Configures using the `courier.apiKey` and `courier.baseUrl` system properties
+// Or configures using the `COURIER_API_KEY` and `COURIER_BASE_URL` environment variables
+CourierClient client = CourierOkHttpClient.fromEnv();
+
+SendMessageParams params = SendMessageParams.builder()
+ .message(SendMessageParams.Message.builder()
+ .to(UserRecipient.builder()
+ .userId("your_user_id")
+ .build())
+ .data(SendMessageParams.Message.Data.builder()
+ .putAdditionalProperty("foo", JsonValue.from("bar"))
+ .build())
+ .build())
+ .build();
+CompletableFuture response = client.async().send().message(params);
+```
+
+Or create an asynchronous client from the beginning:
-Courier courier = Courier.builder()
- .authorizationToken("YOUR_TOKEN") # Defaults to System.getenv("COURIER_AUTHORIZATION_TOKEN")
+```java
+import com.courier.api.client.CourierClientAsync;
+import com.courier.api.client.okhttp.CourierOkHttpClientAsync;
+import com.courier.api.core.JsonValue;
+import com.courier.api.models.bulk.UserRecipient;
+import com.courier.api.models.send.SendMessageParams;
+import com.courier.api.models.send.SendMessageResponse;
+import java.util.concurrent.CompletableFuture;
+
+// Configures using the `courier.apiKey` and `courier.baseUrl` system properties
+// Or configures using the `COURIER_API_KEY` and `COURIER_BASE_URL` environment variables
+CourierClientAsync client = CourierOkHttpClientAsync.fromEnv();
+
+SendMessageParams params = SendMessageParams.builder()
+ .message(SendMessageParams.Message.builder()
+ .to(UserRecipient.builder()
+ .userId("your_user_id")
+ .build())
+ .data(SendMessageParams.Message.Data.builder()
+ .putAdditionalProperty("foo", JsonValue.from("bar"))
+ .build())
+ .build())
.build();
+CompletableFuture response = client.send().message(params);
+```
+
+The asynchronous client supports the same options as the synchronous one, except most methods return `CompletableFuture`s.
+
+## Raw responses
-courier.send(SendMessageRequest.builder()
- .message(Message.of(TemplateMessage.builder()
- .template("")
- .to(MessageRecipient.of(Recipient.of(UserRecipient.builder()
- .email("marty_mcfly@email.com")
- .build())))
- .build()))
- .build());
+The SDK defines methods that deserialize responses into instances of Java classes. However, these methods don't provide access to the response headers, status code, or the raw response body.
+
+To access this data, prefix any HTTP method call on a client or service with `withRawResponse()`:
+
+```java
+import com.courier.api.core.JsonValue;
+import com.courier.api.core.http.Headers;
+import com.courier.api.core.http.HttpResponseFor;
+import com.courier.api.models.bulk.UserRecipient;
+import com.courier.api.models.send.SendMessageParams;
+import com.courier.api.models.send.SendMessageResponse;
+
+SendMessageParams params = SendMessageParams.builder()
+ .message(SendMessageParams.Message.builder()
+ .to(UserRecipient.builder()
+ .userId("your_user_id")
+ .build())
+ .data(SendMessageParams.Message.Data.builder()
+ .putAdditionalProperty("foo", JsonValue.from("bar"))
+ .build())
+ .build())
+ .build();
+HttpResponseFor response = client.send().withRawResponse().message(params);
+
+int statusCode = response.statusCode();
+Headers headers = response.headers();
+```
+
+You can still deserialize the response into an instance of a Java class if needed:
+
+```java
+import com.courier.api.models.send.SendMessageResponse;
+
+SendMessageResponse parsedResponse = response.parse();
```
-## Upgrade Guides
+## Error handling
+
+The SDK throws custom unchecked exception types:
+
+- [`CourierServiceException`](courier-java-core/src/main/kotlin/com/courier/api/errors/CourierServiceException.kt): Base class for HTTP errors. See this table for which exception subclass is thrown for each HTTP status code:
+
+ | Status | Exception |
+ | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
+ | 400 | [`BadRequestException`](courier-java-core/src/main/kotlin/com/courier/api/errors/BadRequestException.kt) |
+ | 401 | [`UnauthorizedException`](courier-java-core/src/main/kotlin/com/courier/api/errors/UnauthorizedException.kt) |
+ | 403 | [`PermissionDeniedException`](courier-java-core/src/main/kotlin/com/courier/api/errors/PermissionDeniedException.kt) |
+ | 404 | [`NotFoundException`](courier-java-core/src/main/kotlin/com/courier/api/errors/NotFoundException.kt) |
+ | 422 | [`UnprocessableEntityException`](courier-java-core/src/main/kotlin/com/courier/api/errors/UnprocessableEntityException.kt) |
+ | 429 | [`RateLimitException`](courier-java-core/src/main/kotlin/com/courier/api/errors/RateLimitException.kt) |
+ | 5xx | [`InternalServerException`](courier-java-core/src/main/kotlin/com/courier/api/errors/InternalServerException.kt) |
+ | others | [`UnexpectedStatusCodeException`](courier-java-core/src/main/kotlin/com/courier/api/errors/UnexpectedStatusCodeException.kt) |
+
+- [`CourierIoException`](courier-java-core/src/main/kotlin/com/courier/api/errors/CourierIoException.kt): I/O networking errors.
+
+- [`CourierRetryableException`](courier-java-core/src/main/kotlin/com/courier/api/errors/CourierRetryableException.kt): Generic error indicating a failure that could be retried by the client.
-### v2 to v3
+- [`CourierInvalidDataException`](courier-java-core/src/main/kotlin/com/courier/api/errors/CourierInvalidDataException.kt): Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.
-v3 of our SDK is automatically generated by [Fern](https://buildwithfern.com/). v3 comes
-with several improvements that we describe below:
+- [`CourierException`](courier-java-core/src/main/kotlin/com/courier/api/errors/CourierException.kt): Base class for all exceptions. Most errors will result in one of the previously mentioned ones, but completely generic errors may be thrown using the base class.
-- **Resource-scoped SDK methods**: Endpoints are scoped under their resource. For
- example, instead of `courier.deleteBrands` the SDK now reads `courier.brands.delete(...)`
-- **Docs on Hover**: All endpoint and parameter level documentation that you see
- on our docs website is now embedded directly within the SDKs.
-- **Retries with exponential backoff**: The SDK will automatically retry failures with
- exponential backoff.
-- **Strongly Typed**: The SDK has Java objects to describe each of our request and
- response models. Each object has a static `builder` method and uses the staged
- builder pattern.
- ```java
- UserRecipient.builder()
- .email("marty_mcfly@email.com")
- .build();
- ```
-- **Unions** The SDK has natively supports unions. Every union is modelled as a java
- class that has static factory methods.
- ```java
- // Message has static factory methods that either take a TemplateMessage or
- // ContentMessage
- Message.of(TemplateMessage.builder()...)
-
- Message.of(ContentMessage.builder()...)
- ```
+## Logging
-## Request Options
-Every endpoint has an overloaded equivalent which takes [RequestOptions](./src/main/java/com/courier/api/core/RequestOptions.java)
-that allow you to override settings for that particular request.
+The SDK uses the standard [OkHttp logging interceptor](https://github.com/square/okhttp/tree/master/okhttp-logging-interceptor).
+
+Enable logging by setting the `COURIER_LOG` environment variable to `info`:
+
+```sh
+$ export COURIER_LOG=info
+```
+
+Or to `debug` for more verbose logging:
+
+```sh
+$ export COURIER_LOG=debug
+```
+
+## ProGuard and R8
+
+Although the SDK uses reflection, it is still usable with [ProGuard](https://github.com/Guardsquare/proguard) and [R8](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization) because `courier-java-core` is published with a [configuration file](courier-java-core/src/main/resources/META-INF/proguard/courier-java-core.pro) containing [keep rules](https://www.guardsquare.com/manual/configuration/usage).
+
+ProGuard and R8 should automatically detect and use the published rules, but you can also manually copy the keep rules if necessary.
+
+## Jackson
+
+The SDK depends on [Jackson](https://github.com/FasterXML/jackson) for JSON serialization/deserialization. It is compatible with version 2.13.4 or higher, but depends on version 2.18.2 by default.
+
+The SDK throws an exception if it detects an incompatible Jackson version at runtime (e.g. if the default version was overridden in your Maven or Gradle config).
+
+If the SDK threw an exception, but you're _certain_ the version is compatible, then disable the version check using the `checkJacksonVersionCompatibility` on [`CourierOkHttpClient`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClient.kt) or [`CourierOkHttpClientAsync`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClientAsync.kt).
+
+> [!CAUTION]
+> We make no guarantee that the SDK works correctly when the Jackson version check is disabled.
+
+## Network options
+
+### Retries
+
+The SDK automatically retries 2 times by default, with a short exponential backoff between requests.
+
+Only the following error types are retried:
+
+- Connection errors (for example, due to a network connectivity problem)
+- 408 Request Timeout
+- 409 Conflict
+- 429 Rate Limit
+- 5xx Internal
+
+The API may also explicitly instruct the SDK to retry or not retry a request.
+
+To set a custom number of retries, configure the client using the `maxRetries` method:
```java
-import com.courier.api.Courier;
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
-courier.brands.get(..., RequestOptions.builder()
- .authorizationToken(...)
- .build())
+CourierClient client = CourierOkHttpClient.builder()
+ .fromEnv()
+ .maxRetries(4)
+ .build();
```
-## Idempotency Headers
-You can specify idempotency headers by providing an `IdempotentRequestOptions` parameter.
+### Timeouts
+
+Requests time out after 1 minute by default.
+
+To set a custom timeout, configure the method call using the `timeout` method:
```java
-import com.courier.api.Courier;
-import java.util.UUID;
+import com.courier.api.models.send.SendMessageResponse;
-courier.send(..., IdempotentRequestOptions.builder()
- .idempotencyKey(UUID.randomUUID().toString())
- .build())
+SendMessageResponse response = client.send().message(
+ params, RequestOptions.builder().timeout(Duration.ofSeconds(30)).build()
+);
```
-## Exception Handling
-All errors thrown by the SDK will be subclasses of `com.courier.api.APIError`.
+Or configure the default for all method calls at the client level:
```java
-import com.courier.api.core.ApiError;
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+import java.time.Duration;
-try {
- courier.brands.get(...)
-} catch (ApiError e) {
- System.out.println(e.statusCode());
- System.out.println(e.body());
+CourierClient client = CourierOkHttpClient.builder()
+ .fromEnv()
+ .timeout(Duration.ofSeconds(30))
+ .build();
+```
+
+### Proxies
+
+To route requests through a proxy, configure the client using the `proxy` method:
+
+```java
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+import java.net.InetSocketAddress;
+import java.net.Proxy;
+
+CourierClient client = CourierOkHttpClient.builder()
+ .fromEnv()
+ .proxy(new Proxy(
+ Proxy.Type.HTTP, new InetSocketAddress(
+ "https://example.com", 8080
+ )
+ ))
+ .build();
+```
+
+### HTTPS
+
+> [!NOTE]
+> Most applications should not call these methods, and instead use the system defaults. The defaults include
+> special optimizations that can be lost if the implementations are modified.
+
+To configure how HTTPS connections are secured, configure the client using the `sslSocketFactory`, `trustManager`, and `hostnameVerifier` methods:
+
+```java
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+
+CourierClient client = CourierOkHttpClient.builder()
+ .fromEnv()
+ // If `sslSocketFactory` is set, then `trustManager` must be set, and vice versa.
+ .sslSocketFactory(yourSSLSocketFactory)
+ .trustManager(yourTrustManager)
+ .hostnameVerifier(yourHostnameVerifier)
+ .build();
+```
+
+### Custom HTTP client
+
+The SDK consists of three artifacts:
+
+- `courier-java-core`
+ - Contains core SDK logic
+ - Does not depend on [OkHttp](https://square.github.io/okhttp)
+ - Exposes [`CourierClient`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClient.kt), [`CourierClientAsync`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsync.kt), [`CourierClientImpl`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientImpl.kt), and [`CourierClientAsyncImpl`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsyncImpl.kt), all of which can work with any HTTP client
+- `courier-java-client-okhttp`
+ - Depends on [OkHttp](https://square.github.io/okhttp)
+ - Exposes [`CourierOkHttpClient`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClient.kt) and [`CourierOkHttpClientAsync`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClientAsync.kt), which provide a way to construct [`CourierClientImpl`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientImpl.kt) and [`CourierClientAsyncImpl`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsyncImpl.kt), respectively, using OkHttp
+- `courier-java`
+ - Depends on and exposes the APIs of both `courier-java-core` and `courier-java-client-okhttp`
+ - Does not have its own logic
+
+This structure allows replacing the SDK's default HTTP client without pulling in unnecessary dependencies.
+
+#### Customized [`OkHttpClient`](https://square.github.io/okhttp/3.x/okhttp/okhttp3/OkHttpClient.html)
+
+> [!TIP]
+> Try the available [network options](#network-options) before replacing the default client.
+
+To use a customized `OkHttpClient`:
+
+1. Replace your [`courier-java` dependency](#installation) with `courier-java-core`
+2. Copy `courier-java-client-okhttp`'s [`OkHttpClient`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/OkHttpClient.kt) class into your code and customize it
+3. Construct [`CourierClientImpl`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientImpl.kt) or [`CourierClientAsyncImpl`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsyncImpl.kt), similarly to [`CourierOkHttpClient`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClient.kt) or [`CourierOkHttpClientAsync`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClientAsync.kt), using your customized client
+
+### Completely custom HTTP client
+
+To use a completely custom HTTP client:
+
+1. Replace your [`courier-java` dependency](#installation) with `courier-java-core`
+2. Write a class that implements the [`HttpClient`](courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpClient.kt) interface
+3. Construct [`CourierClientImpl`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientImpl.kt) or [`CourierClientAsyncImpl`](courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsyncImpl.kt), similarly to [`CourierOkHttpClient`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClient.kt) or [`CourierOkHttpClientAsync`](courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClientAsync.kt), using your new client class
+
+## Undocumented API functionality
+
+The SDK is typed for convenient usage of the documented API. However, it also supports working with undocumented or not yet supported parts of the API.
+
+### Parameters
+
+To set undocumented parameters, call the `putAdditionalHeader`, `putAdditionalQueryParam`, or `putAdditionalBodyProperty` methods on any `Params` class:
+
+```java
+import com.courier.api.core.JsonValue;
+import com.courier.api.models.send.SendMessageParams;
+
+SendMessageParams params = SendMessageParams.builder()
+ .putAdditionalHeader("Secret-Header", "42")
+ .putAdditionalQueryParam("secret_query_param", "42")
+ .putAdditionalBodyProperty("secretProperty", JsonValue.from("42"))
+ .build();
+```
+
+These can be accessed on the built object later using the `_additionalHeaders()`, `_additionalQueryParams()`, and `_additionalBodyProperties()` methods.
+
+To set undocumented parameters on _nested_ headers, query params, or body classes, call the `putAdditionalProperty` method on the nested class:
+
+```java
+import com.courier.api.core.JsonValue;
+import com.courier.api.models.send.SendMessageParams;
+
+SendMessageParams params = SendMessageParams.builder()
+ .message(SendMessageParams.Message.builder()
+ .putAdditionalProperty("secretProperty", JsonValue.from("42"))
+ .build())
+ .build();
+```
+
+These properties can be accessed on the nested built object later using the `_additionalProperties()` method.
+
+To set a documented parameter or property to an undocumented or not yet supported _value_, pass a [`JsonValue`](courier-java-core/src/main/kotlin/com/courier/api/core/Values.kt) object to its setter:
+
+```java
+import com.courier.api.core.JsonValue;
+import com.courier.api.models.send.SendMessageParams;
+
+SendMessageParams params = SendMessageParams.builder()
+ .message(JsonValue.from(42))
+ .build();
+```
+
+The most straightforward way to create a [`JsonValue`](courier-java-core/src/main/kotlin/com/courier/api/core/Values.kt) is using its `from(...)` method:
+
+```java
+import com.courier.api.core.JsonValue;
+import java.util.List;
+import java.util.Map;
+
+// Create primitive JSON values
+JsonValue nullValue = JsonValue.from(null);
+JsonValue booleanValue = JsonValue.from(true);
+JsonValue numberValue = JsonValue.from(42);
+JsonValue stringValue = JsonValue.from("Hello World!");
+
+// Create a JSON array value equivalent to `["Hello", "World"]`
+JsonValue arrayValue = JsonValue.from(List.of(
+ "Hello", "World"
+));
+
+// Create a JSON object value equivalent to `{ "a": 1, "b": 2 }`
+JsonValue objectValue = JsonValue.from(Map.of(
+ "a", 1,
+ "b", 2
+));
+
+// Create an arbitrarily nested JSON equivalent to:
+// {
+// "a": [1, 2],
+// "b": [3, 4]
+// }
+JsonValue complexValue = JsonValue.from(Map.of(
+ "a", List.of(
+ 1, 2
+ ),
+ "b", List.of(
+ 3, 4
+ )
+));
+```
+
+Normally a `Builder` class's `build` method will throw [`IllegalStateException`](https://docs.oracle.com/javase/8/docs/api/java/lang/IllegalStateException.html) if any required parameter or property is unset.
+
+To forcibly omit a required parameter or property, pass [`JsonMissing`](courier-java-core/src/main/kotlin/com/courier/api/core/Values.kt):
+
+```java
+import com.courier.api.core.JsonMissing;
+import com.courier.api.models.send.SendMessageParams;
+
+SendMessageParams params = SendMessageParams.builder()
+ .message(JsonMissing.of())
+ .build();
+```
+
+### Response properties
+
+To access undocumented response properties, call the `_additionalProperties()` method:
+
+```java
+import com.courier.api.core.JsonValue;
+import java.util.Map;
+
+Map additionalProperties = client.send().message(params)._additionalProperties();
+JsonValue secretPropertyValue = additionalProperties.get("secretProperty");
+
+String result = secretPropertyValue.accept(new JsonValue.Visitor<>() {
+ @Override
+ public String visitNull() {
+ return "It's null!";
+ }
+
+ @Override
+ public String visitBoolean(boolean value) {
+ return "It's a boolean!";
+ }
+
+ @Override
+ public String visitNumber(Number value) {
+ return "It's a number!";
+ }
+
+ // Other methods include `visitMissing`, `visitString`, `visitArray`, and `visitObject`
+ // The default implementation of each unimplemented method delegates to `visitDefault`, which throws by default, but can also be overridden
+});
+```
+
+To access a property's raw JSON value, which may be undocumented, call its `_` prefixed method:
+
+```java
+import com.courier.api.core.JsonField;
+import com.courier.api.models.send.SendMessageParams;
+import java.util.Optional;
+
+JsonField message = client.send().message(params)._message();
+
+if (message.isMissing()) {
+ // The property is absent from the JSON response
+} else if (message.isNull()) {
+ // The property was set to literal null
+} else {
+ // Check if value was provided as a string
+ // Other methods include `asNumber()`, `asBoolean()`, etc.
+ Optional jsonString = message.asString();
+
+ // Try to deserialize into a custom type
+ MyClass myObject = message.asUnknown().orElseThrow().convert(MyClass.class);
}
```
-## Retries
-409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried twice
-with exponential backoff.
+### Response validation
+
+In rare cases, the API may return a response that doesn't match the expected type. For example, the SDK may expect a property to contain a `String`, but the API could return something else.
+
+By default, the SDK will not throw an exception in this case. It will throw [`CourierInvalidDataException`](courier-java-core/src/main/kotlin/com/courier/api/errors/CourierInvalidDataException.kt) only if you directly access the property.
+
+If you would prefer to check that the response is completely well-typed upfront, then either call `validate()`:
+
+```java
+import com.courier.api.models.send.SendMessageResponse;
+
+SendMessageResponse response = client.send().message(params).validate();
+```
+
+Or configure the method call to validate the response using the `responseValidation` method:
+
+```java
+import com.courier.api.models.send.SendMessageResponse;
+
+SendMessageResponse response = client.send().message(
+ params, RequestOptions.builder().responseValidation(true).build()
+);
+```
-## Additional Properties
-Sometimes, the server response may include additional properties that are not
-available in the SDK. Use the `getAdditionalProperties()` method to access them.
+Or configure the default for all method calls at the client level:
```java
-Object value = entity.getAdditionalProperties().get("new_prop");
+import com.courier.api.client.CourierClient;
+import com.courier.api.client.okhttp.CourierOkHttpClient;
+
+CourierClient client = CourierOkHttpClient.builder()
+ .fromEnv()
+ .responseValidation(true)
+ .build();
```
-## Contributing
-While we value open-source contributions to this SDK, this library is generated programmatically.
-Additions made directly to this library would have to be moved over to our generation code, otherwise
-they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept,
-but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!
+## FAQ
+
+### Why don't you use plain `enum` classes?
+
+Java `enum` classes are not trivially [forwards compatible](https://www.stainless.com/blog/making-java-enums-forwards-compatible). Using them in the SDK could cause runtime exceptions if the API is updated to respond with a new enum value.
+
+### Why do you represent fields using `JsonField` instead of just plain `T`?
+
+Using `JsonField` enables a few features:
+
+- Allowing usage of [undocumented API functionality](#undocumented-api-functionality)
+- Lazily [validating the API response against the expected shape](#response-validation)
+- Representing absent vs explicitly null values
+
+### Why don't you use [`data` classes](https://kotlinlang.org/docs/data-classes.html)?
+
+It is not [backwards compatible to add new fields to a data class](https://kotlinlang.org/docs/api-guidelines-backward-compatibility.html#avoid-using-data-classes-in-your-api) and we don't want to introduce a breaking change every time we add a field to a class.
+
+### Why don't you use checked exceptions?
+
+Checked exceptions are widely considered a mistake in the Java programming language. In fact, they were omitted from Kotlin for this reason.
+
+Checked exceptions:
+
+- Are verbose to handle
+- Encourage error handling at the wrong level of abstraction, where nothing can be done about the error
+- Are tedious to propagate due to the [function coloring problem](https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function)
+- Don't play well with lambdas (also due to the function coloring problem)
+
+## Semantic versioning
+
+This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
+
+1. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
+2. Changes that we do not expect to impact the vast majority of users in practice.
+
+We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
-On the other hand, contributions to the README are always very welcome!
\ No newline at end of file
+We are keen for your feedback; please open an [issue](https://www.github.com/trycourier/courier-java/issues) with questions, bugs, or suggestions.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..e8a2e774
--- /dev/null
+++ b/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.
diff --git a/bin/check-release-environment b/bin/check-release-environment
new file mode 100644
index 00000000..3a6a7b4a
--- /dev/null
+++ b/bin/check-release-environment
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+errors=()
+
+if [ -z "${SONATYPE_USERNAME}" ]; then
+ errors+=("The SONATYPE_USERNAME secret has not been set. Please set it in either this repository's secrets or your organization secrets")
+fi
+
+if [ -z "${SONATYPE_PASSWORD}" ]; then
+ errors+=("The SONATYPE_PASSWORD secret has not been set. Please set it in either this repository's secrets or your organization secrets")
+fi
+
+if [ -z "${GPG_SIGNING_KEY}" ]; then
+ errors+=("The GPG_SIGNING_KEY secret has not been set. Please set it in either this repository's secrets or your organization secrets")
+fi
+
+if [ -z "${GPG_SIGNING_PASSWORD}" ]; then
+ errors+=("The GPG_SIGNING_PASSWORD secret has not been set. Please set it in either this repository's secrets or your organization secrets")
+fi
+
+lenErrors=${#errors[@]}
+
+if [[ lenErrors -gt 0 ]]; then
+ echo -e "Found the following errors in the release environment:\n"
+
+ for error in "${errors[@]}"; do
+ echo -e "- $error\n"
+ done
+
+ exit 1
+fi
+
+echo "The environment is ready to push releases!"
diff --git a/build.gradle b/build.gradle
deleted file mode 100644
index 2154b2e1..00000000
--- a/build.gradle
+++ /dev/null
@@ -1,88 +0,0 @@
-plugins {
- id 'java-library'
- id 'maven-publish'
- id 'com.diffplug.spotless' version '6.11.0'
- id 'signing'
-}
-
-repositories {
- mavenCentral()
- maven {
- url 'https://oss.sonatype.org/service/local/staging/deploy/maven2/'
- }
-}
-
-dependencies {
- api 'com.squareup.okhttp3:okhttp:4.12.0'
- api 'com.fasterxml.jackson.core:jackson-databind:2.13.0'
- api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.12.3'
- api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.12.3'
- testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
- testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.8.2'
-}
-
-
-sourceCompatibility = 1.8
-targetCompatibility = 1.8
-
-spotless {
- java {
- palantirJavaFormat()
- }
-}
-
-java {
- withSourcesJar()
- withJavadocJar()
-}
-
-signing {
- sign(publishing.publications)
-}
-test {
- useJUnitPlatform()
- testLogging {
- showStandardStreams = true
- }
-}
-publishing {
- publications {
- maven(MavenPublication) {
- groupId = 'com.courier'
- artifactId = 'courier-java'
- version = '3.6.0'
- from components.java
- pom {
- name = 'courier'
- description = 'The official Java library for sending notifications with the Courier REST API.'
- url = 'https://www.courier.com/docs/reference/'
- licenses {
- license {
- name = 'MIT'
- }
- }
- developers {
- developer {
- name = 'courier'
- email = 'developers@courier.com'
- }
- }
- scm {
- connection = 'scm:git:git://github.com/trycourier/courier-java.git'
- developerConnection = 'scm:git:git://github.com/trycourier/courier-java.git'
- url = 'https://github.com/trycourier/courier-java'
- }
- }
- }
- }
- repositories {
- maven {
- url "$System.env.MAVEN_PUBLISH_REGISTRY_URL"
- credentials {
- username "$System.env.MAVEN_USERNAME"
- password "$System.env.MAVEN_PASSWORD"
- }
- }
- }
-}
-
diff --git a/build.gradle.kts b/build.gradle.kts
new file mode 100644
index 00000000..d942981c
--- /dev/null
+++ b/build.gradle.kts
@@ -0,0 +1,49 @@
+plugins {
+ id("io.github.gradle-nexus.publish-plugin") version "1.1.0"
+ id("org.jetbrains.dokka") version "2.0.0"
+}
+
+repositories {
+ mavenCentral()
+}
+
+allprojects {
+ group = "com.courier.api"
+ version = "0.1.0" // x-release-please-version
+}
+
+subprojects {
+ // These are populated with dependencies by `buildSrc` scripts.
+ tasks.register("format") {
+ group = "Verification"
+ description = "Formats all source files."
+ }
+ tasks.register("lint") {
+ group = "Verification"
+ description = "Verifies all source files are formatted."
+ }
+ apply(plugin = "org.jetbrains.dokka")
+}
+
+subprojects {
+ apply(plugin = "org.jetbrains.dokka")
+}
+
+// Avoid race conditions between `dokkaJavadocCollector` and `dokkaJavadocJar` tasks
+tasks.named("dokkaJavadocCollector").configure {
+ subprojects.flatMap { it.tasks }
+ .filter { it.project.name != "courier-java" && it.name == "dokkaJavadocJar" }
+ .forEach { mustRunAfter(it) }
+}
+
+nexusPublishing {
+ repositories {
+ sonatype {
+ nexusUrl.set(uri("https://s01.oss.sonatype.org/service/local/"))
+ snapshotRepositoryUrl.set(uri("https://s01.oss.sonatype.org/content/repositories/snapshots/"))
+
+ username.set(System.getenv("SONATYPE_USERNAME"))
+ password.set(System.getenv("SONATYPE_PASSWORD"))
+ }
+ }
+}
diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts
new file mode 100644
index 00000000..0b141353
--- /dev/null
+++ b/buildSrc/build.gradle.kts
@@ -0,0 +1,12 @@
+plugins {
+ `kotlin-dsl`
+ kotlin("jvm") version "1.9.20"
+}
+
+repositories {
+ gradlePluginPortal()
+}
+
+dependencies {
+ implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.20")
+}
diff --git a/buildSrc/src/main/kotlin/courier.java.gradle.kts b/buildSrc/src/main/kotlin/courier.java.gradle.kts
new file mode 100644
index 00000000..81d5d32b
--- /dev/null
+++ b/buildSrc/src/main/kotlin/courier.java.gradle.kts
@@ -0,0 +1,136 @@
+import org.gradle.api.tasks.testing.logging.TestExceptionFormat
+
+plugins {
+ `java-library`
+}
+
+repositories {
+ mavenCentral()
+}
+
+configure {
+ withJavadocJar()
+ withSourcesJar()
+}
+
+java {
+ toolchain {
+ languageVersion.set(JavaLanguageVersion.of(21))
+ }
+
+ sourceCompatibility = JavaVersion.VERSION_1_8
+ targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+tasks.withType().configureEach {
+ options.compilerArgs.add("-Werror")
+ options.release.set(8)
+}
+
+tasks.named("javadocJar") {
+ setZip64(true)
+}
+
+tasks.named("jar") {
+ manifest {
+ attributes(mapOf(
+ "Implementation-Title" to project.name,
+ "Implementation-Version" to project.version
+ ))
+ }
+}
+
+tasks.withType().configureEach {
+ useJUnitPlatform()
+
+ // Run tests in parallel to some degree.
+ maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).coerceAtLeast(1)
+ forkEvery = 100
+
+ testLogging {
+ exceptionFormat = TestExceptionFormat.FULL
+ }
+}
+
+val palantir by configurations.creating
+dependencies {
+ palantir("com.palantir.javaformat:palantir-java-format:2.73.0")
+}
+
+fun registerPalantir(
+ name: String,
+ description: String,
+) {
+ val javaName = "${name}Java"
+ tasks.register(javaName) {
+ group = "Verification"
+ this.description = description
+
+ classpath = palantir
+ mainClass = "com.palantir.javaformat.java.Main"
+
+ // Avoid an `IllegalAccessError` on Java 9+.
+ jvmArgs(
+ "--add-exports", "jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED",
+ "--add-exports", "jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED",
+ "--add-exports", "jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED",
+ "--add-exports", "jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED",
+ "--add-exports", "jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED",
+ )
+
+ // Use paths relative to the current module.
+ val argumentFile =
+ project.layout.buildDirectory.file("palantir-$name-args.txt").get().asFile
+ val lastRunTimeFile =
+ project.layout.buildDirectory.file("palantir-$name-last-run.txt").get().asFile
+
+ // Read the time when this task was last executed for this module (if ever).
+ val lastRunTime = lastRunTimeFile.takeIf { it.exists() }?.readText()?.toLongOrNull() ?: 0L
+
+ // Use a `fileTree` relative to the module's source directory.
+ val javaFiles = project.fileTree("src") { include("**/*.java") }
+
+ // Determine if any files need to be formatted or linted and continue only if there is at least
+ // one file.
+ onlyIf { javaFiles.any { it.lastModified() > lastRunTime } }
+
+ inputs.files(javaFiles)
+
+ doFirst {
+ // Create the argument file and set the preferred formatting style.
+ argumentFile.parentFile.mkdirs()
+ argumentFile.writeText("--palantir\n")
+
+ if (name == "lint") {
+ // For lint, do a dry run, so no files are modified. Set the exit code to 1 (instead of
+ // the default 0) if any files need to be formatted, indicating that linting has failed.
+ argumentFile.appendText("--dry-run\n")
+ argumentFile.appendText("--set-exit-if-changed\n")
+ } else {
+ // `--dry-run` and `--replace` (for in-place formatting) are mutually exclusive.
+ argumentFile.appendText("--replace\n")
+ }
+
+ // Write the modified files to the argument file.
+ javaFiles.filter { it.lastModified() > lastRunTime }
+ .forEach { argumentFile.appendText("${it.absolutePath}\n") }
+ }
+
+ doLast {
+ // Record the last execution time for later up-to-date checking.
+ lastRunTimeFile.writeText(System.currentTimeMillis().toString())
+ }
+
+ // Pass the argument file using the @ symbol
+ args = listOf("@${argumentFile.absolutePath}")
+
+ outputs.upToDateWhen { javaFiles.none { it.lastModified() > lastRunTime } }
+ }
+
+ tasks.named(name) {
+ dependsOn(tasks.named(javaName))
+ }
+}
+
+registerPalantir(name = "format", description = "Formats all Java source files.")
+registerPalantir(name = "lint", description = "Verifies all Java source files are formatted.")
diff --git a/buildSrc/src/main/kotlin/courier.kotlin.gradle.kts b/buildSrc/src/main/kotlin/courier.kotlin.gradle.kts
new file mode 100644
index 00000000..365ccefa
--- /dev/null
+++ b/buildSrc/src/main/kotlin/courier.kotlin.gradle.kts
@@ -0,0 +1,106 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
+
+plugins {
+ id("courier.java")
+ kotlin("jvm")
+}
+
+repositories {
+ mavenCentral()
+}
+
+kotlin {
+ jvmToolchain {
+ languageVersion.set(JavaLanguageVersion.of(21))
+ }
+
+ compilerOptions {
+ freeCompilerArgs = listOf(
+ "-Xjvm-default=all",
+ "-Xjdk-release=1.8",
+ // Suppress deprecation warnings because we may still reference and test deprecated members.
+ // TODO: Replace with `-Xsuppress-warning=DEPRECATION` once we use Kotlin compiler 2.1.0+.
+ "-nowarn",
+ )
+ jvmTarget.set(JvmTarget.JVM_1_8)
+ languageVersion.set(KotlinVersion.KOTLIN_1_8)
+ apiVersion.set(KotlinVersion.KOTLIN_1_8)
+ coreLibrariesVersion = "1.8.0"
+ }
+}
+
+tasks.withType().configureEach {
+ systemProperty("junit.jupiter.execution.parallel.enabled", true)
+ systemProperty("junit.jupiter.execution.parallel.mode.default", "concurrent")
+}
+
+val ktfmt by configurations.creating
+dependencies {
+ ktfmt("com.facebook:ktfmt:0.56")
+}
+
+fun registerKtfmt(
+ name: String,
+ description: String,
+) {
+ val kotlinName = "${name}Kotlin"
+ tasks.register(kotlinName) {
+ group = "Verification"
+ this.description = description
+
+ classpath = ktfmt
+ mainClass = "com.facebook.ktfmt.cli.Main"
+
+ // Use paths relative to the current module.
+ val argumentFile = project.layout.buildDirectory.file("ktfmt-$name-args.txt").get().asFile
+ val lastRunTimeFile =
+ project.layout.buildDirectory.file("ktfmt-$name-last-run.txt").get().asFile
+
+ // Read the time when this task was last executed for this module (if ever).
+ val lastRunTime = lastRunTimeFile.takeIf { it.exists() }?.readText()?.toLongOrNull() ?: 0L
+
+ // Use a `fileTree` relative to the module's source directory.
+ val kotlinFiles = project.fileTree("src") { include("**/*.kt") }
+
+ // Determine if any files need to be formatted or linted and continue only if there is at least
+ // one file (otherwise Ktfmt will fail).
+ onlyIf { kotlinFiles.any { it.lastModified() > lastRunTime } }
+
+ inputs.files(kotlinFiles)
+
+ doFirst {
+ // Create the argument file and set the preferred formatting style.
+ argumentFile.parentFile.mkdirs()
+ argumentFile.writeText("--kotlinlang-style\n")
+
+ if (name == "lint") {
+ // For lint, do a dry run, so no files are modified. Set the exit code to 1 (instead of
+ // the default 0) if any files need to be formatted, indicating that linting has failed.
+ argumentFile.appendText("--dry-run\n")
+ argumentFile.appendText("--set-exit-if-changed\n")
+ }
+
+ // Write the modified files to the argument file.
+ kotlinFiles.filter { it.lastModified() > lastRunTime }
+ .forEach { argumentFile.appendText("${it.absolutePath}\n") }
+ }
+
+ doLast {
+ // Record the last execution time for later up-to-date checking.
+ lastRunTimeFile.writeText(System.currentTimeMillis().toString())
+ }
+
+ // Pass the argument file using the @ symbol
+ args = listOf("@${argumentFile.absolutePath}")
+
+ outputs.upToDateWhen { kotlinFiles.none { it.lastModified() > lastRunTime } }
+ }
+
+ tasks.named(name) {
+ dependsOn(tasks.named(kotlinName))
+ }
+}
+
+registerKtfmt(name = "format", description = "Formats all Kotlin source files.")
+registerKtfmt(name = "lint", description = "Verifies all Kotlin source files are formatted.")
diff --git a/buildSrc/src/main/kotlin/courier.publish.gradle.kts b/buildSrc/src/main/kotlin/courier.publish.gradle.kts
new file mode 100644
index 00000000..e36e7d24
--- /dev/null
+++ b/buildSrc/src/main/kotlin/courier.publish.gradle.kts
@@ -0,0 +1,60 @@
+plugins {
+ `maven-publish`
+ signing
+}
+
+configure {
+ publications {
+ register("maven") {
+ from(components["java"])
+
+ pom {
+ name.set("Courier")
+ description.set("An SDK library for courier")
+ url.set("https://www.github.com/trycourier/courier-java")
+
+ licenses {
+ license {
+ name.set("Apache-2.0")
+ }
+ }
+
+ developers {
+ developer {
+ name.set("Courier")
+ }
+ }
+
+ scm {
+ connection.set("scm:git:git://github.com/trycourier/courier-java.git")
+ developerConnection.set("scm:git:git://github.com/trycourier/courier-java.git")
+ url.set("https://github.com/trycourier/courier-java")
+ }
+
+ versionMapping {
+ allVariants {
+ fromResolutionResult()
+ }
+ }
+ }
+ }
+ }
+}
+
+signing {
+ val signingKeyId = System.getenv("GPG_SIGNING_KEY_ID")?.ifBlank { null }
+ val signingKey = System.getenv("GPG_SIGNING_KEY")?.ifBlank { null }
+ val signingPassword = System.getenv("GPG_SIGNING_PASSWORD")?.ifBlank { null }
+ if (signingKey != null && signingPassword != null) {
+ useInMemoryPgpKeys(
+ signingKeyId,
+ signingKey,
+ signingPassword,
+ )
+ sign(publishing.publications["maven"])
+ }
+}
+
+tasks.named("publish") {
+ dependsOn(":closeAndReleaseSonatypeStagingRepository")
+}
diff --git a/courier-java-client-okhttp/build.gradle.kts b/courier-java-client-okhttp/build.gradle.kts
new file mode 100644
index 00000000..4b62416c
--- /dev/null
+++ b/courier-java-client-okhttp/build.gradle.kts
@@ -0,0 +1,14 @@
+plugins {
+ id("courier.kotlin")
+ id("courier.publish")
+}
+
+dependencies {
+ api(project(":courier-java-core"))
+
+ implementation("com.squareup.okhttp3:okhttp:4.12.0")
+ implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
+
+ testImplementation(kotlin("test"))
+ testImplementation("org.assertj:assertj-core:3.25.3")
+}
diff --git a/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClient.kt b/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClient.kt
new file mode 100644
index 00000000..4ff91a1b
--- /dev/null
+++ b/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClient.kt
@@ -0,0 +1,307 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.client.okhttp
+
+import com.courier.api.client.CourierClient
+import com.courier.api.client.CourierClientImpl
+import com.courier.api.core.ClientOptions
+import com.courier.api.core.Sleeper
+import com.courier.api.core.Timeout
+import com.courier.api.core.http.Headers
+import com.courier.api.core.http.HttpClient
+import com.courier.api.core.http.QueryParams
+import com.courier.api.core.jsonMapper
+import com.fasterxml.jackson.databind.json.JsonMapper
+import java.net.Proxy
+import java.time.Clock
+import java.time.Duration
+import java.util.Optional
+import javax.net.ssl.HostnameVerifier
+import javax.net.ssl.SSLSocketFactory
+import javax.net.ssl.X509TrustManager
+import kotlin.jvm.optionals.getOrNull
+
+/**
+ * A class that allows building an instance of [CourierClient] with [OkHttpClient] as the underlying
+ * [HttpClient].
+ */
+class CourierOkHttpClient private constructor() {
+
+ companion object {
+
+ /** Returns a mutable builder for constructing an instance of [CourierClient]. */
+ @JvmStatic fun builder() = Builder()
+
+ /**
+ * Returns a client configured using system properties and environment variables.
+ *
+ * @see ClientOptions.Builder.fromEnv
+ */
+ @JvmStatic fun fromEnv(): CourierClient = builder().fromEnv().build()
+ }
+
+ /** A builder for [CourierOkHttpClient]. */
+ class Builder internal constructor() {
+
+ private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
+ private var proxy: Proxy? = null
+ private var sslSocketFactory: SSLSocketFactory? = null
+ private var trustManager: X509TrustManager? = null
+ private var hostnameVerifier: HostnameVerifier? = null
+
+ fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
+
+ /** Alias for calling [Builder.proxy] with `proxy.orElse(null)`. */
+ fun proxy(proxy: Optional) = proxy(proxy.getOrNull())
+
+ /**
+ * The socket factory used to secure HTTPS connections.
+ *
+ * If this is set, then [trustManager] must also be set.
+ *
+ * If unset, then the system default is used. Most applications should not call this method,
+ * and instead use the system default. The default include special optimizations that can be
+ * lost if the implementation is modified.
+ */
+ fun sslSocketFactory(sslSocketFactory: SSLSocketFactory?) = apply {
+ this.sslSocketFactory = sslSocketFactory
+ }
+
+ /** Alias for calling [Builder.sslSocketFactory] with `sslSocketFactory.orElse(null)`. */
+ fun sslSocketFactory(sslSocketFactory: Optional) =
+ sslSocketFactory(sslSocketFactory.getOrNull())
+
+ /**
+ * The trust manager used to secure HTTPS connections.
+ *
+ * If this is set, then [sslSocketFactory] must also be set.
+ *
+ * If unset, then the system default is used. Most applications should not call this method,
+ * and instead use the system default. The default include special optimizations that can be
+ * lost if the implementation is modified.
+ */
+ fun trustManager(trustManager: X509TrustManager?) = apply {
+ this.trustManager = trustManager
+ }
+
+ /** Alias for calling [Builder.trustManager] with `trustManager.orElse(null)`. */
+ fun trustManager(trustManager: Optional) =
+ trustManager(trustManager.getOrNull())
+
+ /**
+ * The verifier used to confirm that response certificates apply to requested hostnames for
+ * HTTPS connections.
+ *
+ * If unset, then a default hostname verifier is used.
+ */
+ fun hostnameVerifier(hostnameVerifier: HostnameVerifier?) = apply {
+ this.hostnameVerifier = hostnameVerifier
+ }
+
+ /** Alias for calling [Builder.hostnameVerifier] with `hostnameVerifier.orElse(null)`. */
+ fun hostnameVerifier(hostnameVerifier: Optional) =
+ hostnameVerifier(hostnameVerifier.getOrNull())
+
+ /**
+ * Whether to throw an exception if any of the Jackson versions detected at runtime are
+ * incompatible with the SDK's minimum supported Jackson version (2.13.4).
+ *
+ * Defaults to true. Use extreme caution when disabling this option. There is no guarantee
+ * that the SDK will work correctly when using an incompatible Jackson version.
+ */
+ fun checkJacksonVersionCompatibility(checkJacksonVersionCompatibility: Boolean) = apply {
+ clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
+ }
+
+ /**
+ * The Jackson JSON mapper to use for serializing and deserializing JSON.
+ *
+ * Defaults to [com.courier.api.core.jsonMapper]. The default is usually sufficient and
+ * rarely needs to be overridden.
+ */
+ fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
+
+ /**
+ * The interface to use for delaying execution, like during retries.
+ *
+ * This is primarily useful for using fake delays in tests.
+ *
+ * Defaults to real execution delays.
+ *
+ * This class takes ownership of the sleeper and closes it when closed.
+ */
+ fun sleeper(sleeper: Sleeper) = apply { clientOptions.sleeper(sleeper) }
+
+ /**
+ * The clock to use for operations that require timing, like retries.
+ *
+ * This is primarily useful for using a fake clock in tests.
+ *
+ * Defaults to [Clock.systemUTC].
+ */
+ fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
+
+ /**
+ * The base URL to use for every request.
+ *
+ * Defaults to the production environment: `https://api.courier.com`.
+ */
+ fun baseUrl(baseUrl: String?) = apply { clientOptions.baseUrl(baseUrl) }
+
+ /** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
+ fun baseUrl(baseUrl: Optional) = baseUrl(baseUrl.getOrNull())
+
+ /**
+ * Whether to call `validate` on every response before returning it.
+ *
+ * Defaults to false, which means the shape of the response will not be validated upfront.
+ * Instead, validation will only occur for the parts of the response that are accessed.
+ */
+ fun responseValidation(responseValidation: Boolean) = apply {
+ clientOptions.responseValidation(responseValidation)
+ }
+
+ /**
+ * Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
+ * retries.
+ *
+ * Defaults to [Timeout.default].
+ */
+ fun timeout(timeout: Timeout) = apply { clientOptions.timeout(timeout) }
+
+ /**
+ * Sets the maximum time allowed for a complete HTTP call, not including retries.
+ *
+ * See [Timeout.request] for more details.
+ *
+ * For fine-grained control, pass a [Timeout] object.
+ */
+ fun timeout(timeout: Duration) = apply { clientOptions.timeout(timeout) }
+
+ /**
+ * The maximum number of times to retry failed requests, with a short exponential backoff
+ * between requests.
+ *
+ * Only the following error types are retried:
+ * - Connection errors (for example, due to a network connectivity problem)
+ * - 408 Request Timeout
+ * - 409 Conflict
+ * - 429 Rate Limit
+ * - 5xx Internal
+ *
+ * The API may also explicitly instruct the SDK to retry or not retry a request.
+ *
+ * Defaults to 2.
+ */
+ fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
+
+ fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
+
+ fun headers(headers: Headers) = apply { clientOptions.headers(headers) }
+
+ fun headers(headers: Map>) = apply {
+ clientOptions.headers(headers)
+ }
+
+ fun putHeader(name: String, value: String) = apply { clientOptions.putHeader(name, value) }
+
+ fun putHeaders(name: String, values: Iterable) = apply {
+ clientOptions.putHeaders(name, values)
+ }
+
+ fun putAllHeaders(headers: Headers) = apply { clientOptions.putAllHeaders(headers) }
+
+ fun putAllHeaders(headers: Map>) = apply {
+ clientOptions.putAllHeaders(headers)
+ }
+
+ fun replaceHeaders(name: String, value: String) = apply {
+ clientOptions.replaceHeaders(name, value)
+ }
+
+ fun replaceHeaders(name: String, values: Iterable) = apply {
+ clientOptions.replaceHeaders(name, values)
+ }
+
+ fun replaceAllHeaders(headers: Headers) = apply { clientOptions.replaceAllHeaders(headers) }
+
+ fun replaceAllHeaders(headers: Map>) = apply {
+ clientOptions.replaceAllHeaders(headers)
+ }
+
+ fun removeHeaders(name: String) = apply { clientOptions.removeHeaders(name) }
+
+ fun removeAllHeaders(names: Set) = apply { clientOptions.removeAllHeaders(names) }
+
+ fun queryParams(queryParams: QueryParams) = apply { clientOptions.queryParams(queryParams) }
+
+ fun queryParams(queryParams: Map>) = apply {
+ clientOptions.queryParams(queryParams)
+ }
+
+ fun putQueryParam(key: String, value: String) = apply {
+ clientOptions.putQueryParam(key, value)
+ }
+
+ fun putQueryParams(key: String, values: Iterable) = apply {
+ clientOptions.putQueryParams(key, values)
+ }
+
+ fun putAllQueryParams(queryParams: QueryParams) = apply {
+ clientOptions.putAllQueryParams(queryParams)
+ }
+
+ fun putAllQueryParams(queryParams: Map>) = apply {
+ clientOptions.putAllQueryParams(queryParams)
+ }
+
+ fun replaceQueryParams(key: String, value: String) = apply {
+ clientOptions.replaceQueryParams(key, value)
+ }
+
+ fun replaceQueryParams(key: String, values: Iterable) = apply {
+ clientOptions.replaceQueryParams(key, values)
+ }
+
+ fun replaceAllQueryParams(queryParams: QueryParams) = apply {
+ clientOptions.replaceAllQueryParams(queryParams)
+ }
+
+ fun replaceAllQueryParams(queryParams: Map>) = apply {
+ clientOptions.replaceAllQueryParams(queryParams)
+ }
+
+ fun removeQueryParams(key: String) = apply { clientOptions.removeQueryParams(key) }
+
+ fun removeAllQueryParams(keys: Set) = apply {
+ clientOptions.removeAllQueryParams(keys)
+ }
+
+ /**
+ * Updates configuration using system properties and environment variables.
+ *
+ * @see ClientOptions.Builder.fromEnv
+ */
+ fun fromEnv() = apply { clientOptions.fromEnv() }
+
+ /**
+ * Returns an immutable instance of [CourierClient].
+ *
+ * Further updates to this [Builder] will not mutate the returned instance.
+ */
+ fun build(): CourierClient =
+ CourierClientImpl(
+ clientOptions
+ .httpClient(
+ OkHttpClient.builder()
+ .timeout(clientOptions.timeout())
+ .proxy(proxy)
+ .sslSocketFactory(sslSocketFactory)
+ .trustManager(trustManager)
+ .hostnameVerifier(hostnameVerifier)
+ .build()
+ )
+ .build()
+ )
+ }
+}
diff --git a/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClientAsync.kt b/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClientAsync.kt
new file mode 100644
index 00000000..9360f485
--- /dev/null
+++ b/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/CourierOkHttpClientAsync.kt
@@ -0,0 +1,307 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.client.okhttp
+
+import com.courier.api.client.CourierClientAsync
+import com.courier.api.client.CourierClientAsyncImpl
+import com.courier.api.core.ClientOptions
+import com.courier.api.core.Sleeper
+import com.courier.api.core.Timeout
+import com.courier.api.core.http.Headers
+import com.courier.api.core.http.HttpClient
+import com.courier.api.core.http.QueryParams
+import com.courier.api.core.jsonMapper
+import com.fasterxml.jackson.databind.json.JsonMapper
+import java.net.Proxy
+import java.time.Clock
+import java.time.Duration
+import java.util.Optional
+import javax.net.ssl.HostnameVerifier
+import javax.net.ssl.SSLSocketFactory
+import javax.net.ssl.X509TrustManager
+import kotlin.jvm.optionals.getOrNull
+
+/**
+ * A class that allows building an instance of [CourierClientAsync] with [OkHttpClient] as the
+ * underlying [HttpClient].
+ */
+class CourierOkHttpClientAsync private constructor() {
+
+ companion object {
+
+ /** Returns a mutable builder for constructing an instance of [CourierClientAsync]. */
+ @JvmStatic fun builder() = Builder()
+
+ /**
+ * Returns a client configured using system properties and environment variables.
+ *
+ * @see ClientOptions.Builder.fromEnv
+ */
+ @JvmStatic fun fromEnv(): CourierClientAsync = builder().fromEnv().build()
+ }
+
+ /** A builder for [CourierOkHttpClientAsync]. */
+ class Builder internal constructor() {
+
+ private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
+ private var proxy: Proxy? = null
+ private var sslSocketFactory: SSLSocketFactory? = null
+ private var trustManager: X509TrustManager? = null
+ private var hostnameVerifier: HostnameVerifier? = null
+
+ fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
+
+ /** Alias for calling [Builder.proxy] with `proxy.orElse(null)`. */
+ fun proxy(proxy: Optional) = proxy(proxy.getOrNull())
+
+ /**
+ * The socket factory used to secure HTTPS connections.
+ *
+ * If this is set, then [trustManager] must also be set.
+ *
+ * If unset, then the system default is used. Most applications should not call this method,
+ * and instead use the system default. The default include special optimizations that can be
+ * lost if the implementation is modified.
+ */
+ fun sslSocketFactory(sslSocketFactory: SSLSocketFactory?) = apply {
+ this.sslSocketFactory = sslSocketFactory
+ }
+
+ /** Alias for calling [Builder.sslSocketFactory] with `sslSocketFactory.orElse(null)`. */
+ fun sslSocketFactory(sslSocketFactory: Optional) =
+ sslSocketFactory(sslSocketFactory.getOrNull())
+
+ /**
+ * The trust manager used to secure HTTPS connections.
+ *
+ * If this is set, then [sslSocketFactory] must also be set.
+ *
+ * If unset, then the system default is used. Most applications should not call this method,
+ * and instead use the system default. The default include special optimizations that can be
+ * lost if the implementation is modified.
+ */
+ fun trustManager(trustManager: X509TrustManager?) = apply {
+ this.trustManager = trustManager
+ }
+
+ /** Alias for calling [Builder.trustManager] with `trustManager.orElse(null)`. */
+ fun trustManager(trustManager: Optional) =
+ trustManager(trustManager.getOrNull())
+
+ /**
+ * The verifier used to confirm that response certificates apply to requested hostnames for
+ * HTTPS connections.
+ *
+ * If unset, then a default hostname verifier is used.
+ */
+ fun hostnameVerifier(hostnameVerifier: HostnameVerifier?) = apply {
+ this.hostnameVerifier = hostnameVerifier
+ }
+
+ /** Alias for calling [Builder.hostnameVerifier] with `hostnameVerifier.orElse(null)`. */
+ fun hostnameVerifier(hostnameVerifier: Optional) =
+ hostnameVerifier(hostnameVerifier.getOrNull())
+
+ /**
+ * Whether to throw an exception if any of the Jackson versions detected at runtime are
+ * incompatible with the SDK's minimum supported Jackson version (2.13.4).
+ *
+ * Defaults to true. Use extreme caution when disabling this option. There is no guarantee
+ * that the SDK will work correctly when using an incompatible Jackson version.
+ */
+ fun checkJacksonVersionCompatibility(checkJacksonVersionCompatibility: Boolean) = apply {
+ clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
+ }
+
+ /**
+ * The Jackson JSON mapper to use for serializing and deserializing JSON.
+ *
+ * Defaults to [com.courier.api.core.jsonMapper]. The default is usually sufficient and
+ * rarely needs to be overridden.
+ */
+ fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
+
+ /**
+ * The interface to use for delaying execution, like during retries.
+ *
+ * This is primarily useful for using fake delays in tests.
+ *
+ * Defaults to real execution delays.
+ *
+ * This class takes ownership of the sleeper and closes it when closed.
+ */
+ fun sleeper(sleeper: Sleeper) = apply { clientOptions.sleeper(sleeper) }
+
+ /**
+ * The clock to use for operations that require timing, like retries.
+ *
+ * This is primarily useful for using a fake clock in tests.
+ *
+ * Defaults to [Clock.systemUTC].
+ */
+ fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
+
+ /**
+ * The base URL to use for every request.
+ *
+ * Defaults to the production environment: `https://api.courier.com`.
+ */
+ fun baseUrl(baseUrl: String?) = apply { clientOptions.baseUrl(baseUrl) }
+
+ /** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
+ fun baseUrl(baseUrl: Optional) = baseUrl(baseUrl.getOrNull())
+
+ /**
+ * Whether to call `validate` on every response before returning it.
+ *
+ * Defaults to false, which means the shape of the response will not be validated upfront.
+ * Instead, validation will only occur for the parts of the response that are accessed.
+ */
+ fun responseValidation(responseValidation: Boolean) = apply {
+ clientOptions.responseValidation(responseValidation)
+ }
+
+ /**
+ * Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
+ * retries.
+ *
+ * Defaults to [Timeout.default].
+ */
+ fun timeout(timeout: Timeout) = apply { clientOptions.timeout(timeout) }
+
+ /**
+ * Sets the maximum time allowed for a complete HTTP call, not including retries.
+ *
+ * See [Timeout.request] for more details.
+ *
+ * For fine-grained control, pass a [Timeout] object.
+ */
+ fun timeout(timeout: Duration) = apply { clientOptions.timeout(timeout) }
+
+ /**
+ * The maximum number of times to retry failed requests, with a short exponential backoff
+ * between requests.
+ *
+ * Only the following error types are retried:
+ * - Connection errors (for example, due to a network connectivity problem)
+ * - 408 Request Timeout
+ * - 409 Conflict
+ * - 429 Rate Limit
+ * - 5xx Internal
+ *
+ * The API may also explicitly instruct the SDK to retry or not retry a request.
+ *
+ * Defaults to 2.
+ */
+ fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
+
+ fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
+
+ fun headers(headers: Headers) = apply { clientOptions.headers(headers) }
+
+ fun headers(headers: Map>) = apply {
+ clientOptions.headers(headers)
+ }
+
+ fun putHeader(name: String, value: String) = apply { clientOptions.putHeader(name, value) }
+
+ fun putHeaders(name: String, values: Iterable) = apply {
+ clientOptions.putHeaders(name, values)
+ }
+
+ fun putAllHeaders(headers: Headers) = apply { clientOptions.putAllHeaders(headers) }
+
+ fun putAllHeaders(headers: Map>) = apply {
+ clientOptions.putAllHeaders(headers)
+ }
+
+ fun replaceHeaders(name: String, value: String) = apply {
+ clientOptions.replaceHeaders(name, value)
+ }
+
+ fun replaceHeaders(name: String, values: Iterable) = apply {
+ clientOptions.replaceHeaders(name, values)
+ }
+
+ fun replaceAllHeaders(headers: Headers) = apply { clientOptions.replaceAllHeaders(headers) }
+
+ fun replaceAllHeaders(headers: Map>) = apply {
+ clientOptions.replaceAllHeaders(headers)
+ }
+
+ fun removeHeaders(name: String) = apply { clientOptions.removeHeaders(name) }
+
+ fun removeAllHeaders(names: Set) = apply { clientOptions.removeAllHeaders(names) }
+
+ fun queryParams(queryParams: QueryParams) = apply { clientOptions.queryParams(queryParams) }
+
+ fun queryParams(queryParams: Map>) = apply {
+ clientOptions.queryParams(queryParams)
+ }
+
+ fun putQueryParam(key: String, value: String) = apply {
+ clientOptions.putQueryParam(key, value)
+ }
+
+ fun putQueryParams(key: String, values: Iterable) = apply {
+ clientOptions.putQueryParams(key, values)
+ }
+
+ fun putAllQueryParams(queryParams: QueryParams) = apply {
+ clientOptions.putAllQueryParams(queryParams)
+ }
+
+ fun putAllQueryParams(queryParams: Map>) = apply {
+ clientOptions.putAllQueryParams(queryParams)
+ }
+
+ fun replaceQueryParams(key: String, value: String) = apply {
+ clientOptions.replaceQueryParams(key, value)
+ }
+
+ fun replaceQueryParams(key: String, values: Iterable) = apply {
+ clientOptions.replaceQueryParams(key, values)
+ }
+
+ fun replaceAllQueryParams(queryParams: QueryParams) = apply {
+ clientOptions.replaceAllQueryParams(queryParams)
+ }
+
+ fun replaceAllQueryParams(queryParams: Map>) = apply {
+ clientOptions.replaceAllQueryParams(queryParams)
+ }
+
+ fun removeQueryParams(key: String) = apply { clientOptions.removeQueryParams(key) }
+
+ fun removeAllQueryParams(keys: Set) = apply {
+ clientOptions.removeAllQueryParams(keys)
+ }
+
+ /**
+ * Updates configuration using system properties and environment variables.
+ *
+ * @see ClientOptions.Builder.fromEnv
+ */
+ fun fromEnv() = apply { clientOptions.fromEnv() }
+
+ /**
+ * Returns an immutable instance of [CourierClientAsync].
+ *
+ * Further updates to this [Builder] will not mutate the returned instance.
+ */
+ fun build(): CourierClientAsync =
+ CourierClientAsyncImpl(
+ clientOptions
+ .httpClient(
+ OkHttpClient.builder()
+ .timeout(clientOptions.timeout())
+ .proxy(proxy)
+ .sslSocketFactory(sslSocketFactory)
+ .trustManager(trustManager)
+ .hostnameVerifier(hostnameVerifier)
+ .build()
+ )
+ .build()
+ )
+ }
+}
diff --git a/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/OkHttpClient.kt b/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/OkHttpClient.kt
new file mode 100644
index 00000000..33ff3abe
--- /dev/null
+++ b/courier-java-client-okhttp/src/main/kotlin/com/courier/api/client/okhttp/OkHttpClient.kt
@@ -0,0 +1,246 @@
+package com.courier.api.client.okhttp
+
+import com.courier.api.core.RequestOptions
+import com.courier.api.core.Timeout
+import com.courier.api.core.http.Headers
+import com.courier.api.core.http.HttpClient
+import com.courier.api.core.http.HttpMethod
+import com.courier.api.core.http.HttpRequest
+import com.courier.api.core.http.HttpRequestBody
+import com.courier.api.core.http.HttpResponse
+import com.courier.api.errors.CourierIoException
+import java.io.IOException
+import java.io.InputStream
+import java.net.Proxy
+import java.time.Duration
+import java.util.concurrent.CompletableFuture
+import javax.net.ssl.HostnameVerifier
+import javax.net.ssl.SSLSocketFactory
+import javax.net.ssl.X509TrustManager
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.HttpUrl.Companion.toHttpUrl
+import okhttp3.MediaType
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.Request
+import okhttp3.RequestBody
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.Response
+import okhttp3.logging.HttpLoggingInterceptor
+import okio.BufferedSink
+
+class OkHttpClient private constructor(private val okHttpClient: okhttp3.OkHttpClient) :
+ HttpClient {
+
+ override fun execute(request: HttpRequest, requestOptions: RequestOptions): HttpResponse {
+ val call = newCall(request, requestOptions)
+
+ return try {
+ call.execute().toResponse()
+ } catch (e: IOException) {
+ throw CourierIoException("Request failed", e)
+ } finally {
+ request.body?.close()
+ }
+ }
+
+ override fun executeAsync(
+ request: HttpRequest,
+ requestOptions: RequestOptions,
+ ): CompletableFuture {
+ val future = CompletableFuture()
+
+ request.body?.run { future.whenComplete { _, _ -> close() } }
+
+ newCall(request, requestOptions)
+ .enqueue(
+ object : Callback {
+ override fun onResponse(call: Call, response: Response) {
+ future.complete(response.toResponse())
+ }
+
+ override fun onFailure(call: Call, e: IOException) {
+ future.completeExceptionally(CourierIoException("Request failed", e))
+ }
+ }
+ )
+
+ return future
+ }
+
+ override fun close() {
+ okHttpClient.dispatcher.executorService.shutdown()
+ okHttpClient.connectionPool.evictAll()
+ okHttpClient.cache?.close()
+ }
+
+ private fun newCall(request: HttpRequest, requestOptions: RequestOptions): Call {
+ val clientBuilder = okHttpClient.newBuilder()
+
+ val logLevel =
+ when (System.getenv("COURIER_LOG")?.lowercase()) {
+ "info" -> HttpLoggingInterceptor.Level.BASIC
+ "debug" -> HttpLoggingInterceptor.Level.BODY
+ else -> null
+ }
+ if (logLevel != null) {
+ clientBuilder.addNetworkInterceptor(
+ HttpLoggingInterceptor().setLevel(logLevel).apply { redactHeader("Authorization") }
+ )
+ }
+
+ requestOptions.timeout?.let {
+ clientBuilder
+ .connectTimeout(it.connect())
+ .readTimeout(it.read())
+ .writeTimeout(it.write())
+ .callTimeout(it.request())
+ }
+
+ val client = clientBuilder.build()
+ return client.newCall(request.toRequest(client))
+ }
+
+ private fun HttpRequest.toRequest(client: okhttp3.OkHttpClient): Request {
+ var body: RequestBody? = body?.toRequestBody()
+ if (body == null && requiresBody(method)) {
+ body = "".toRequestBody()
+ }
+
+ val builder = Request.Builder().url(toUrl()).method(method.name, body)
+ headers.names().forEach { name ->
+ headers.values(name).forEach { builder.header(name, it) }
+ }
+
+ if (
+ !headers.names().contains("X-Stainless-Read-Timeout") && client.readTimeoutMillis != 0
+ ) {
+ builder.header(
+ "X-Stainless-Read-Timeout",
+ Duration.ofMillis(client.readTimeoutMillis.toLong()).seconds.toString(),
+ )
+ }
+ if (!headers.names().contains("X-Stainless-Timeout") && client.callTimeoutMillis != 0) {
+ builder.header(
+ "X-Stainless-Timeout",
+ Duration.ofMillis(client.callTimeoutMillis.toLong()).seconds.toString(),
+ )
+ }
+
+ return builder.build()
+ }
+
+ /** `OkHttpClient` always requires a request body for some methods. */
+ private fun requiresBody(method: HttpMethod): Boolean =
+ when (method) {
+ HttpMethod.POST,
+ HttpMethod.PUT,
+ HttpMethod.PATCH -> true
+ else -> false
+ }
+
+ private fun HttpRequest.toUrl(): String {
+ val builder = baseUrl.toHttpUrl().newBuilder()
+ pathSegments.forEach(builder::addPathSegment)
+ queryParams.keys().forEach { key ->
+ queryParams.values(key).forEach { builder.addQueryParameter(key, it) }
+ }
+
+ return builder.toString()
+ }
+
+ private fun HttpRequestBody.toRequestBody(): RequestBody {
+ val mediaType = contentType()?.toMediaType()
+ val length = contentLength()
+
+ return object : RequestBody() {
+ override fun contentType(): MediaType? = mediaType
+
+ override fun contentLength(): Long = length
+
+ override fun isOneShot(): Boolean = !repeatable()
+
+ override fun writeTo(sink: BufferedSink) = writeTo(sink.outputStream())
+ }
+ }
+
+ private fun Response.toResponse(): HttpResponse {
+ val headers = headers.toHeaders()
+
+ return object : HttpResponse {
+ override fun statusCode(): Int = code
+
+ override fun headers(): Headers = headers
+
+ override fun body(): InputStream = body!!.byteStream()
+
+ override fun close() = body!!.close()
+ }
+ }
+
+ private fun okhttp3.Headers.toHeaders(): Headers {
+ val headersBuilder = Headers.builder()
+ forEach { (name, value) -> headersBuilder.put(name, value) }
+ return headersBuilder.build()
+ }
+
+ companion object {
+ @JvmStatic fun builder() = Builder()
+ }
+
+ class Builder internal constructor() {
+
+ private var timeout: Timeout = Timeout.default()
+ private var proxy: Proxy? = null
+ private var sslSocketFactory: SSLSocketFactory? = null
+ private var trustManager: X509TrustManager? = null
+ private var hostnameVerifier: HostnameVerifier? = null
+
+ fun timeout(timeout: Timeout) = apply { this.timeout = timeout }
+
+ fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
+
+ fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
+
+ fun sslSocketFactory(sslSocketFactory: SSLSocketFactory?) = apply {
+ this.sslSocketFactory = sslSocketFactory
+ }
+
+ fun trustManager(trustManager: X509TrustManager?) = apply {
+ this.trustManager = trustManager
+ }
+
+ fun hostnameVerifier(hostnameVerifier: HostnameVerifier?) = apply {
+ this.hostnameVerifier = hostnameVerifier
+ }
+
+ fun build(): OkHttpClient =
+ OkHttpClient(
+ okhttp3.OkHttpClient.Builder()
+ .connectTimeout(timeout.connect())
+ .readTimeout(timeout.read())
+ .writeTimeout(timeout.write())
+ .callTimeout(timeout.request())
+ .proxy(proxy)
+ .apply {
+ val sslSocketFactory = sslSocketFactory
+ val trustManager = trustManager
+ if (sslSocketFactory != null && trustManager != null) {
+ sslSocketFactory(sslSocketFactory, trustManager)
+ } else {
+ check((sslSocketFactory != null) == (trustManager != null)) {
+ "Both or none of `sslSocketFactory` and `trustManager` must be set, but only one was set"
+ }
+ }
+
+ hostnameVerifier?.let(::hostnameVerifier)
+ }
+ .build()
+ .apply {
+ // We usually make all our requests to the same host so it makes sense to
+ // raise the per-host limit to the overall limit.
+ dispatcher.maxRequestsPerHost = dispatcher.maxRequests
+ }
+ )
+ }
+}
diff --git a/courier-java-core/build.gradle.kts b/courier-java-core/build.gradle.kts
new file mode 100644
index 00000000..d31e4b11
--- /dev/null
+++ b/courier-java-core/build.gradle.kts
@@ -0,0 +1,41 @@
+plugins {
+ id("courier.kotlin")
+ id("courier.publish")
+}
+
+configurations.all {
+ resolutionStrategy {
+ // Compile and test against a lower Jackson version to ensure we're compatible with it.
+ // We publish with a higher version (see below) to ensure users depend on a secure version by default.
+ force("com.fasterxml.jackson.core:jackson-core:2.13.4")
+ force("com.fasterxml.jackson.core:jackson-databind:2.13.4")
+ force("com.fasterxml.jackson.core:jackson-annotations:2.13.4")
+ force("com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.13.4")
+ force("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.13.4")
+ force("com.fasterxml.jackson.module:jackson-module-kotlin:2.13.4")
+ }
+}
+
+dependencies {
+ api("com.fasterxml.jackson.core:jackson-core:2.18.2")
+ api("com.fasterxml.jackson.core:jackson-databind:2.18.2")
+ api("com.google.errorprone:error_prone_annotations:2.33.0")
+
+ implementation("com.fasterxml.jackson.core:jackson-annotations:2.18.2")
+ implementation("com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.2")
+ implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.2")
+ implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.2")
+ implementation("org.apache.httpcomponents.core5:httpcore5:5.2.4")
+ implementation("org.apache.httpcomponents.client5:httpclient5:5.3.1")
+
+ testImplementation(kotlin("test"))
+ testImplementation(project(":courier-java-client-okhttp"))
+ testImplementation("com.github.tomakehurst:wiremock-jre8:2.35.2")
+ testImplementation("org.assertj:assertj-core:3.25.3")
+ testImplementation("org.junit.jupiter:junit-jupiter-api:5.9.3")
+ testImplementation("org.junit.jupiter:junit-jupiter-params:5.9.3")
+ testImplementation("org.junit-pioneer:junit-pioneer:1.9.1")
+ testImplementation("org.mockito:mockito-core:5.14.2")
+ testImplementation("org.mockito:mockito-junit-jupiter:5.14.2")
+ testImplementation("org.mockito.kotlin:mockito-kotlin:4.1.0")
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClient.kt b/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClient.kt
new file mode 100644
index 00000000..40eafc21
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClient.kt
@@ -0,0 +1,147 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.client
+
+import com.courier.api.core.ClientOptions
+import com.courier.api.services.blocking.AudienceService
+import com.courier.api.services.blocking.AuditEventService
+import com.courier.api.services.blocking.AuthService
+import com.courier.api.services.blocking.AutomationService
+import com.courier.api.services.blocking.BrandService
+import com.courier.api.services.blocking.BulkService
+import com.courier.api.services.blocking.InboundService
+import com.courier.api.services.blocking.ListService
+import com.courier.api.services.blocking.MessageService
+import com.courier.api.services.blocking.NotificationService
+import com.courier.api.services.blocking.ProfileService
+import com.courier.api.services.blocking.RequestService
+import com.courier.api.services.blocking.SendService
+import com.courier.api.services.blocking.TenantService
+import com.courier.api.services.blocking.TranslationService
+import com.courier.api.services.blocking.UserService
+import java.util.function.Consumer
+
+/**
+ * A client for interacting with the Courier REST API synchronously. You can also switch to
+ * asynchronous execution via the [async] method.
+ *
+ * This client performs best when you create a single instance and reuse it for all interactions
+ * with the REST API. This is because each client holds its own connection pool and thread pools.
+ * Reusing connections and threads reduces latency and saves memory. The client also handles rate
+ * limiting per client. This means that creating and using multiple instances at the same time will
+ * not respect rate limits.
+ *
+ * The threads and connections that are held will be released automatically if they remain idle. But
+ * if you are writing an application that needs to aggressively release unused resources, then you
+ * may call [close].
+ */
+interface CourierClient {
+
+ /**
+ * Returns a version of this client that uses asynchronous execution.
+ *
+ * The returned client shares its resources, like its connection pool and thread pools, with
+ * this client.
+ */
+ fun async(): CourierClientAsync
+
+ /**
+ * Returns a view of this service that provides access to raw HTTP responses for each method.
+ */
+ fun withRawResponse(): WithRawResponse
+
+ /**
+ * Returns a view of this service with the given option modifications applied.
+ *
+ * The original service is not modified.
+ */
+ fun withOptions(modifier: Consumer): CourierClient
+
+ fun send(): SendService
+
+ fun tenants(): TenantService
+
+ fun audiences(): AudienceService
+
+ fun bulk(): BulkService
+
+ fun users(): UserService
+
+ fun auditEvents(): AuditEventService
+
+ fun automations(): AutomationService
+
+ fun brands(): BrandService
+
+ fun lists(): ListService
+
+ fun messages(): MessageService
+
+ fun notifications(): NotificationService
+
+ fun auth(): AuthService
+
+ fun inbound(): InboundService
+
+ fun requests(): RequestService
+
+ fun profiles(): ProfileService
+
+ fun translations(): TranslationService
+
+ /**
+ * Closes this client, relinquishing any underlying resources.
+ *
+ * This is purposefully not inherited from [AutoCloseable] because the client is long-lived and
+ * usually should not be synchronously closed via try-with-resources.
+ *
+ * It's also usually not necessary to call this method at all. the default HTTP client
+ * automatically releases threads and connections if they remain idle, but if you are writing an
+ * application that needs to aggressively release unused resources, then you may call this
+ * method.
+ */
+ fun close()
+
+ /** A view of [CourierClient] that provides access to raw HTTP responses for each method. */
+ interface WithRawResponse {
+
+ /**
+ * Returns a view of this service with the given option modifications applied.
+ *
+ * The original service is not modified.
+ */
+ fun withOptions(modifier: Consumer): CourierClient.WithRawResponse
+
+ fun send(): SendService.WithRawResponse
+
+ fun tenants(): TenantService.WithRawResponse
+
+ fun audiences(): AudienceService.WithRawResponse
+
+ fun bulk(): BulkService.WithRawResponse
+
+ fun users(): UserService.WithRawResponse
+
+ fun auditEvents(): AuditEventService.WithRawResponse
+
+ fun automations(): AutomationService.WithRawResponse
+
+ fun brands(): BrandService.WithRawResponse
+
+ fun lists(): ListService.WithRawResponse
+
+ fun messages(): MessageService.WithRawResponse
+
+ fun notifications(): NotificationService.WithRawResponse
+
+ fun auth(): AuthService.WithRawResponse
+
+ fun inbound(): InboundService.WithRawResponse
+
+ fun requests(): RequestService.WithRawResponse
+
+ fun profiles(): ProfileService.WithRawResponse
+
+ fun translations(): TranslationService.WithRawResponse
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsync.kt b/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsync.kt
new file mode 100644
index 00000000..ba61d964
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsync.kt
@@ -0,0 +1,151 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.client
+
+import com.courier.api.core.ClientOptions
+import com.courier.api.services.async.AudienceServiceAsync
+import com.courier.api.services.async.AuditEventServiceAsync
+import com.courier.api.services.async.AuthServiceAsync
+import com.courier.api.services.async.AutomationServiceAsync
+import com.courier.api.services.async.BrandServiceAsync
+import com.courier.api.services.async.BulkServiceAsync
+import com.courier.api.services.async.InboundServiceAsync
+import com.courier.api.services.async.ListServiceAsync
+import com.courier.api.services.async.MessageServiceAsync
+import com.courier.api.services.async.NotificationServiceAsync
+import com.courier.api.services.async.ProfileServiceAsync
+import com.courier.api.services.async.RequestServiceAsync
+import com.courier.api.services.async.SendServiceAsync
+import com.courier.api.services.async.TenantServiceAsync
+import com.courier.api.services.async.TranslationServiceAsync
+import com.courier.api.services.async.UserServiceAsync
+import java.util.function.Consumer
+
+/**
+ * A client for interacting with the Courier REST API asynchronously. You can also switch to
+ * synchronous execution via the [sync] method.
+ *
+ * This client performs best when you create a single instance and reuse it for all interactions
+ * with the REST API. This is because each client holds its own connection pool and thread pools.
+ * Reusing connections and threads reduces latency and saves memory. The client also handles rate
+ * limiting per client. This means that creating and using multiple instances at the same time will
+ * not respect rate limits.
+ *
+ * The threads and connections that are held will be released automatically if they remain idle. But
+ * if you are writing an application that needs to aggressively release unused resources, then you
+ * may call [close].
+ */
+interface CourierClientAsync {
+
+ /**
+ * Returns a version of this client that uses synchronous execution.
+ *
+ * The returned client shares its resources, like its connection pool and thread pools, with
+ * this client.
+ */
+ fun sync(): CourierClient
+
+ /**
+ * Returns a view of this service that provides access to raw HTTP responses for each method.
+ */
+ fun withRawResponse(): WithRawResponse
+
+ /**
+ * Returns a view of this service with the given option modifications applied.
+ *
+ * The original service is not modified.
+ */
+ fun withOptions(modifier: Consumer): CourierClientAsync
+
+ fun send(): SendServiceAsync
+
+ fun tenants(): TenantServiceAsync
+
+ fun audiences(): AudienceServiceAsync
+
+ fun bulk(): BulkServiceAsync
+
+ fun users(): UserServiceAsync
+
+ fun auditEvents(): AuditEventServiceAsync
+
+ fun automations(): AutomationServiceAsync
+
+ fun brands(): BrandServiceAsync
+
+ fun lists(): ListServiceAsync
+
+ fun messages(): MessageServiceAsync
+
+ fun notifications(): NotificationServiceAsync
+
+ fun auth(): AuthServiceAsync
+
+ fun inbound(): InboundServiceAsync
+
+ fun requests(): RequestServiceAsync
+
+ fun profiles(): ProfileServiceAsync
+
+ fun translations(): TranslationServiceAsync
+
+ /**
+ * Closes this client, relinquishing any underlying resources.
+ *
+ * This is purposefully not inherited from [AutoCloseable] because the client is long-lived and
+ * usually should not be synchronously closed via try-with-resources.
+ *
+ * It's also usually not necessary to call this method at all. the default HTTP client
+ * automatically releases threads and connections if they remain idle, but if you are writing an
+ * application that needs to aggressively release unused resources, then you may call this
+ * method.
+ */
+ fun close()
+
+ /**
+ * A view of [CourierClientAsync] that provides access to raw HTTP responses for each method.
+ */
+ interface WithRawResponse {
+
+ /**
+ * Returns a view of this service with the given option modifications applied.
+ *
+ * The original service is not modified.
+ */
+ fun withOptions(
+ modifier: Consumer
+ ): CourierClientAsync.WithRawResponse
+
+ fun send(): SendServiceAsync.WithRawResponse
+
+ fun tenants(): TenantServiceAsync.WithRawResponse
+
+ fun audiences(): AudienceServiceAsync.WithRawResponse
+
+ fun bulk(): BulkServiceAsync.WithRawResponse
+
+ fun users(): UserServiceAsync.WithRawResponse
+
+ fun auditEvents(): AuditEventServiceAsync.WithRawResponse
+
+ fun automations(): AutomationServiceAsync.WithRawResponse
+
+ fun brands(): BrandServiceAsync.WithRawResponse
+
+ fun lists(): ListServiceAsync.WithRawResponse
+
+ fun messages(): MessageServiceAsync.WithRawResponse
+
+ fun notifications(): NotificationServiceAsync.WithRawResponse
+
+ fun auth(): AuthServiceAsync.WithRawResponse
+
+ fun inbound(): InboundServiceAsync.WithRawResponse
+
+ fun requests(): RequestServiceAsync.WithRawResponse
+
+ fun profiles(): ProfileServiceAsync.WithRawResponse
+
+ fun translations(): TranslationServiceAsync.WithRawResponse
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsyncImpl.kt b/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsyncImpl.kt
new file mode 100644
index 00000000..a202cd8d
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientAsyncImpl.kt
@@ -0,0 +1,259 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.client
+
+import com.courier.api.core.ClientOptions
+import com.courier.api.core.getPackageVersion
+import com.courier.api.services.async.AudienceServiceAsync
+import com.courier.api.services.async.AudienceServiceAsyncImpl
+import com.courier.api.services.async.AuditEventServiceAsync
+import com.courier.api.services.async.AuditEventServiceAsyncImpl
+import com.courier.api.services.async.AuthServiceAsync
+import com.courier.api.services.async.AuthServiceAsyncImpl
+import com.courier.api.services.async.AutomationServiceAsync
+import com.courier.api.services.async.AutomationServiceAsyncImpl
+import com.courier.api.services.async.BrandServiceAsync
+import com.courier.api.services.async.BrandServiceAsyncImpl
+import com.courier.api.services.async.BulkServiceAsync
+import com.courier.api.services.async.BulkServiceAsyncImpl
+import com.courier.api.services.async.InboundServiceAsync
+import com.courier.api.services.async.InboundServiceAsyncImpl
+import com.courier.api.services.async.ListServiceAsync
+import com.courier.api.services.async.ListServiceAsyncImpl
+import com.courier.api.services.async.MessageServiceAsync
+import com.courier.api.services.async.MessageServiceAsyncImpl
+import com.courier.api.services.async.NotificationServiceAsync
+import com.courier.api.services.async.NotificationServiceAsyncImpl
+import com.courier.api.services.async.ProfileServiceAsync
+import com.courier.api.services.async.ProfileServiceAsyncImpl
+import com.courier.api.services.async.RequestServiceAsync
+import com.courier.api.services.async.RequestServiceAsyncImpl
+import com.courier.api.services.async.SendServiceAsync
+import com.courier.api.services.async.SendServiceAsyncImpl
+import com.courier.api.services.async.TenantServiceAsync
+import com.courier.api.services.async.TenantServiceAsyncImpl
+import com.courier.api.services.async.TranslationServiceAsync
+import com.courier.api.services.async.TranslationServiceAsyncImpl
+import com.courier.api.services.async.UserServiceAsync
+import com.courier.api.services.async.UserServiceAsyncImpl
+import java.util.function.Consumer
+
+class CourierClientAsyncImpl(private val clientOptions: ClientOptions) : CourierClientAsync {
+
+ private val clientOptionsWithUserAgent =
+ if (clientOptions.headers.names().contains("User-Agent")) clientOptions
+ else
+ clientOptions
+ .toBuilder()
+ .putHeader("User-Agent", "${javaClass.simpleName}/Java ${getPackageVersion()}")
+ .build()
+
+ // Pass the original clientOptions so that this client sets its own User-Agent.
+ private val sync: CourierClient by lazy { CourierClientImpl(clientOptions) }
+
+ private val withRawResponse: CourierClientAsync.WithRawResponse by lazy {
+ WithRawResponseImpl(clientOptions)
+ }
+
+ private val send: SendServiceAsync by lazy { SendServiceAsyncImpl(clientOptionsWithUserAgent) }
+
+ private val tenants: TenantServiceAsync by lazy {
+ TenantServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val audiences: AudienceServiceAsync by lazy {
+ AudienceServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val bulk: BulkServiceAsync by lazy { BulkServiceAsyncImpl(clientOptionsWithUserAgent) }
+
+ private val users: UserServiceAsync by lazy { UserServiceAsyncImpl(clientOptionsWithUserAgent) }
+
+ private val auditEvents: AuditEventServiceAsync by lazy {
+ AuditEventServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val automations: AutomationServiceAsync by lazy {
+ AutomationServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val brands: BrandServiceAsync by lazy {
+ BrandServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val lists: ListServiceAsync by lazy { ListServiceAsyncImpl(clientOptionsWithUserAgent) }
+
+ private val messages: MessageServiceAsync by lazy {
+ MessageServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val notifications: NotificationServiceAsync by lazy {
+ NotificationServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val auth: AuthServiceAsync by lazy { AuthServiceAsyncImpl(clientOptionsWithUserAgent) }
+
+ private val inbound: InboundServiceAsync by lazy {
+ InboundServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val requests: RequestServiceAsync by lazy {
+ RequestServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val profiles: ProfileServiceAsync by lazy {
+ ProfileServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ private val translations: TranslationServiceAsync by lazy {
+ TranslationServiceAsyncImpl(clientOptionsWithUserAgent)
+ }
+
+ override fun sync(): CourierClient = sync
+
+ override fun withRawResponse(): CourierClientAsync.WithRawResponse = withRawResponse
+
+ override fun withOptions(modifier: Consumer): CourierClientAsync =
+ CourierClientAsyncImpl(clientOptions.toBuilder().apply(modifier::accept).build())
+
+ override fun send(): SendServiceAsync = send
+
+ override fun tenants(): TenantServiceAsync = tenants
+
+ override fun audiences(): AudienceServiceAsync = audiences
+
+ override fun bulk(): BulkServiceAsync = bulk
+
+ override fun users(): UserServiceAsync = users
+
+ override fun auditEvents(): AuditEventServiceAsync = auditEvents
+
+ override fun automations(): AutomationServiceAsync = automations
+
+ override fun brands(): BrandServiceAsync = brands
+
+ override fun lists(): ListServiceAsync = lists
+
+ override fun messages(): MessageServiceAsync = messages
+
+ override fun notifications(): NotificationServiceAsync = notifications
+
+ override fun auth(): AuthServiceAsync = auth
+
+ override fun inbound(): InboundServiceAsync = inbound
+
+ override fun requests(): RequestServiceAsync = requests
+
+ override fun profiles(): ProfileServiceAsync = profiles
+
+ override fun translations(): TranslationServiceAsync = translations
+
+ override fun close() = clientOptions.close()
+
+ class WithRawResponseImpl internal constructor(private val clientOptions: ClientOptions) :
+ CourierClientAsync.WithRawResponse {
+
+ private val send: SendServiceAsync.WithRawResponse by lazy {
+ SendServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val tenants: TenantServiceAsync.WithRawResponse by lazy {
+ TenantServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val audiences: AudienceServiceAsync.WithRawResponse by lazy {
+ AudienceServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val bulk: BulkServiceAsync.WithRawResponse by lazy {
+ BulkServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val users: UserServiceAsync.WithRawResponse by lazy {
+ UserServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val auditEvents: AuditEventServiceAsync.WithRawResponse by lazy {
+ AuditEventServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val automations: AutomationServiceAsync.WithRawResponse by lazy {
+ AutomationServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val brands: BrandServiceAsync.WithRawResponse by lazy {
+ BrandServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val lists: ListServiceAsync.WithRawResponse by lazy {
+ ListServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val messages: MessageServiceAsync.WithRawResponse by lazy {
+ MessageServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val notifications: NotificationServiceAsync.WithRawResponse by lazy {
+ NotificationServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val auth: AuthServiceAsync.WithRawResponse by lazy {
+ AuthServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val inbound: InboundServiceAsync.WithRawResponse by lazy {
+ InboundServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val requests: RequestServiceAsync.WithRawResponse by lazy {
+ RequestServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val profiles: ProfileServiceAsync.WithRawResponse by lazy {
+ ProfileServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val translations: TranslationServiceAsync.WithRawResponse by lazy {
+ TranslationServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ override fun withOptions(
+ modifier: Consumer
+ ): CourierClientAsync.WithRawResponse =
+ CourierClientAsyncImpl.WithRawResponseImpl(
+ clientOptions.toBuilder().apply(modifier::accept).build()
+ )
+
+ override fun send(): SendServiceAsync.WithRawResponse = send
+
+ override fun tenants(): TenantServiceAsync.WithRawResponse = tenants
+
+ override fun audiences(): AudienceServiceAsync.WithRawResponse = audiences
+
+ override fun bulk(): BulkServiceAsync.WithRawResponse = bulk
+
+ override fun users(): UserServiceAsync.WithRawResponse = users
+
+ override fun auditEvents(): AuditEventServiceAsync.WithRawResponse = auditEvents
+
+ override fun automations(): AutomationServiceAsync.WithRawResponse = automations
+
+ override fun brands(): BrandServiceAsync.WithRawResponse = brands
+
+ override fun lists(): ListServiceAsync.WithRawResponse = lists
+
+ override fun messages(): MessageServiceAsync.WithRawResponse = messages
+
+ override fun notifications(): NotificationServiceAsync.WithRawResponse = notifications
+
+ override fun auth(): AuthServiceAsync.WithRawResponse = auth
+
+ override fun inbound(): InboundServiceAsync.WithRawResponse = inbound
+
+ override fun requests(): RequestServiceAsync.WithRawResponse = requests
+
+ override fun profiles(): ProfileServiceAsync.WithRawResponse = profiles
+
+ override fun translations(): TranslationServiceAsync.WithRawResponse = translations
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientImpl.kt b/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientImpl.kt
new file mode 100644
index 00000000..1c35f756
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/client/CourierClientImpl.kt
@@ -0,0 +1,247 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.client
+
+import com.courier.api.core.ClientOptions
+import com.courier.api.core.getPackageVersion
+import com.courier.api.services.blocking.AudienceService
+import com.courier.api.services.blocking.AudienceServiceImpl
+import com.courier.api.services.blocking.AuditEventService
+import com.courier.api.services.blocking.AuditEventServiceImpl
+import com.courier.api.services.blocking.AuthService
+import com.courier.api.services.blocking.AuthServiceImpl
+import com.courier.api.services.blocking.AutomationService
+import com.courier.api.services.blocking.AutomationServiceImpl
+import com.courier.api.services.blocking.BrandService
+import com.courier.api.services.blocking.BrandServiceImpl
+import com.courier.api.services.blocking.BulkService
+import com.courier.api.services.blocking.BulkServiceImpl
+import com.courier.api.services.blocking.InboundService
+import com.courier.api.services.blocking.InboundServiceImpl
+import com.courier.api.services.blocking.ListService
+import com.courier.api.services.blocking.ListServiceImpl
+import com.courier.api.services.blocking.MessageService
+import com.courier.api.services.blocking.MessageServiceImpl
+import com.courier.api.services.blocking.NotificationService
+import com.courier.api.services.blocking.NotificationServiceImpl
+import com.courier.api.services.blocking.ProfileService
+import com.courier.api.services.blocking.ProfileServiceImpl
+import com.courier.api.services.blocking.RequestService
+import com.courier.api.services.blocking.RequestServiceImpl
+import com.courier.api.services.blocking.SendService
+import com.courier.api.services.blocking.SendServiceImpl
+import com.courier.api.services.blocking.TenantService
+import com.courier.api.services.blocking.TenantServiceImpl
+import com.courier.api.services.blocking.TranslationService
+import com.courier.api.services.blocking.TranslationServiceImpl
+import com.courier.api.services.blocking.UserService
+import com.courier.api.services.blocking.UserServiceImpl
+import java.util.function.Consumer
+
+class CourierClientImpl(private val clientOptions: ClientOptions) : CourierClient {
+
+ private val clientOptionsWithUserAgent =
+ if (clientOptions.headers.names().contains("User-Agent")) clientOptions
+ else
+ clientOptions
+ .toBuilder()
+ .putHeader("User-Agent", "${javaClass.simpleName}/Java ${getPackageVersion()}")
+ .build()
+
+ // Pass the original clientOptions so that this client sets its own User-Agent.
+ private val async: CourierClientAsync by lazy { CourierClientAsyncImpl(clientOptions) }
+
+ private val withRawResponse: CourierClient.WithRawResponse by lazy {
+ WithRawResponseImpl(clientOptions)
+ }
+
+ private val send: SendService by lazy { SendServiceImpl(clientOptionsWithUserAgent) }
+
+ private val tenants: TenantService by lazy { TenantServiceImpl(clientOptionsWithUserAgent) }
+
+ private val audiences: AudienceService by lazy {
+ AudienceServiceImpl(clientOptionsWithUserAgent)
+ }
+
+ private val bulk: BulkService by lazy { BulkServiceImpl(clientOptionsWithUserAgent) }
+
+ private val users: UserService by lazy { UserServiceImpl(clientOptionsWithUserAgent) }
+
+ private val auditEvents: AuditEventService by lazy {
+ AuditEventServiceImpl(clientOptionsWithUserAgent)
+ }
+
+ private val automations: AutomationService by lazy {
+ AutomationServiceImpl(clientOptionsWithUserAgent)
+ }
+
+ private val brands: BrandService by lazy { BrandServiceImpl(clientOptionsWithUserAgent) }
+
+ private val lists: ListService by lazy { ListServiceImpl(clientOptionsWithUserAgent) }
+
+ private val messages: MessageService by lazy { MessageServiceImpl(clientOptionsWithUserAgent) }
+
+ private val notifications: NotificationService by lazy {
+ NotificationServiceImpl(clientOptionsWithUserAgent)
+ }
+
+ private val auth: AuthService by lazy { AuthServiceImpl(clientOptionsWithUserAgent) }
+
+ private val inbound: InboundService by lazy { InboundServiceImpl(clientOptionsWithUserAgent) }
+
+ private val requests: RequestService by lazy { RequestServiceImpl(clientOptionsWithUserAgent) }
+
+ private val profiles: ProfileService by lazy { ProfileServiceImpl(clientOptionsWithUserAgent) }
+
+ private val translations: TranslationService by lazy {
+ TranslationServiceImpl(clientOptionsWithUserAgent)
+ }
+
+ override fun async(): CourierClientAsync = async
+
+ override fun withRawResponse(): CourierClient.WithRawResponse = withRawResponse
+
+ override fun withOptions(modifier: Consumer): CourierClient =
+ CourierClientImpl(clientOptions.toBuilder().apply(modifier::accept).build())
+
+ override fun send(): SendService = send
+
+ override fun tenants(): TenantService = tenants
+
+ override fun audiences(): AudienceService = audiences
+
+ override fun bulk(): BulkService = bulk
+
+ override fun users(): UserService = users
+
+ override fun auditEvents(): AuditEventService = auditEvents
+
+ override fun automations(): AutomationService = automations
+
+ override fun brands(): BrandService = brands
+
+ override fun lists(): ListService = lists
+
+ override fun messages(): MessageService = messages
+
+ override fun notifications(): NotificationService = notifications
+
+ override fun auth(): AuthService = auth
+
+ override fun inbound(): InboundService = inbound
+
+ override fun requests(): RequestService = requests
+
+ override fun profiles(): ProfileService = profiles
+
+ override fun translations(): TranslationService = translations
+
+ override fun close() = clientOptions.close()
+
+ class WithRawResponseImpl internal constructor(private val clientOptions: ClientOptions) :
+ CourierClient.WithRawResponse {
+
+ private val send: SendService.WithRawResponse by lazy {
+ SendServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val tenants: TenantService.WithRawResponse by lazy {
+ TenantServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val audiences: AudienceService.WithRawResponse by lazy {
+ AudienceServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val bulk: BulkService.WithRawResponse by lazy {
+ BulkServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val users: UserService.WithRawResponse by lazy {
+ UserServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val auditEvents: AuditEventService.WithRawResponse by lazy {
+ AuditEventServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val automations: AutomationService.WithRawResponse by lazy {
+ AutomationServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val brands: BrandService.WithRawResponse by lazy {
+ BrandServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val lists: ListService.WithRawResponse by lazy {
+ ListServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val messages: MessageService.WithRawResponse by lazy {
+ MessageServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val notifications: NotificationService.WithRawResponse by lazy {
+ NotificationServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val auth: AuthService.WithRawResponse by lazy {
+ AuthServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val inbound: InboundService.WithRawResponse by lazy {
+ InboundServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val requests: RequestService.WithRawResponse by lazy {
+ RequestServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val profiles: ProfileService.WithRawResponse by lazy {
+ ProfileServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ private val translations: TranslationService.WithRawResponse by lazy {
+ TranslationServiceImpl.WithRawResponseImpl(clientOptions)
+ }
+
+ override fun withOptions(
+ modifier: Consumer
+ ): CourierClient.WithRawResponse =
+ CourierClientImpl.WithRawResponseImpl(
+ clientOptions.toBuilder().apply(modifier::accept).build()
+ )
+
+ override fun send(): SendService.WithRawResponse = send
+
+ override fun tenants(): TenantService.WithRawResponse = tenants
+
+ override fun audiences(): AudienceService.WithRawResponse = audiences
+
+ override fun bulk(): BulkService.WithRawResponse = bulk
+
+ override fun users(): UserService.WithRawResponse = users
+
+ override fun auditEvents(): AuditEventService.WithRawResponse = auditEvents
+
+ override fun automations(): AutomationService.WithRawResponse = automations
+
+ override fun brands(): BrandService.WithRawResponse = brands
+
+ override fun lists(): ListService.WithRawResponse = lists
+
+ override fun messages(): MessageService.WithRawResponse = messages
+
+ override fun notifications(): NotificationService.WithRawResponse = notifications
+
+ override fun auth(): AuthService.WithRawResponse = auth
+
+ override fun inbound(): InboundService.WithRawResponse = inbound
+
+ override fun requests(): RequestService.WithRawResponse = requests
+
+ override fun profiles(): ProfileService.WithRawResponse = profiles
+
+ override fun translations(): TranslationService.WithRawResponse = translations
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/BaseDeserializer.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/BaseDeserializer.kt
new file mode 100644
index 00000000..6210d0dd
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/BaseDeserializer.kt
@@ -0,0 +1,44 @@
+package com.courier.api.core
+
+import com.fasterxml.jackson.core.JsonParser
+import com.fasterxml.jackson.core.ObjectCodec
+import com.fasterxml.jackson.core.type.TypeReference
+import com.fasterxml.jackson.databind.BeanProperty
+import com.fasterxml.jackson.databind.DeserializationContext
+import com.fasterxml.jackson.databind.JavaType
+import com.fasterxml.jackson.databind.JsonDeserializer
+import com.fasterxml.jackson.databind.JsonNode
+import com.fasterxml.jackson.databind.deser.ContextualDeserializer
+import com.fasterxml.jackson.databind.deser.std.StdDeserializer
+import kotlin.reflect.KClass
+
+abstract class BaseDeserializer(type: KClass) :
+ StdDeserializer(type.java), ContextualDeserializer {
+
+ override fun createContextual(
+ context: DeserializationContext,
+ property: BeanProperty?,
+ ): JsonDeserializer {
+ return this
+ }
+
+ override fun deserialize(parser: JsonParser, context: DeserializationContext): T {
+ return parser.codec.deserialize(parser.readValueAsTree())
+ }
+
+ protected abstract fun ObjectCodec.deserialize(node: JsonNode): T
+
+ protected fun ObjectCodec.tryDeserialize(node: JsonNode, type: TypeReference): T? =
+ try {
+ readValue(treeAsTokens(node), type)
+ } catch (e: Exception) {
+ null
+ }
+
+ protected fun ObjectCodec.tryDeserialize(node: JsonNode, type: JavaType): T? =
+ try {
+ readValue(treeAsTokens(node), type)
+ } catch (e: Exception) {
+ null
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/BaseSerializer.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/BaseSerializer.kt
new file mode 100644
index 00000000..b62dd939
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/BaseSerializer.kt
@@ -0,0 +1,6 @@
+package com.courier.api.core
+
+import com.fasterxml.jackson.databind.ser.std.StdSerializer
+import kotlin.reflect.KClass
+
+abstract class BaseSerializer(type: KClass) : StdSerializer(type.java)
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/Check.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/Check.kt
new file mode 100644
index 00000000..fee5b0d4
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/Check.kt
@@ -0,0 +1,96 @@
+@file:JvmName("Check")
+
+package com.courier.api.core
+
+import com.fasterxml.jackson.core.Version
+import com.fasterxml.jackson.core.util.VersionUtil
+
+fun checkRequired(name: String, condition: Boolean) =
+ check(condition) { "`$name` is required, but was not set" }
+
+fun checkRequired(name: String, value: T?): T =
+ checkNotNull(value) { "`$name` is required, but was not set" }
+
+@JvmSynthetic
+internal fun checkKnown(name: String, value: JsonField): T =
+ value.asKnown().orElseThrow {
+ IllegalStateException("`$name` is not a known type: ${value.javaClass.simpleName}")
+ }
+
+@JvmSynthetic
+internal fun checkKnown(name: String, value: MultipartField): T =
+ value.value.asKnown().orElseThrow {
+ IllegalStateException("`$name` is not a known type: ${value.javaClass.simpleName}")
+ }
+
+@JvmSynthetic
+internal fun checkLength(name: String, value: String, length: Int): String =
+ value.also {
+ check(it.length == length) { "`$name` must have length $length, but was ${it.length}" }
+ }
+
+@JvmSynthetic
+internal fun checkMinLength(name: String, value: String, minLength: Int): String =
+ value.also {
+ check(it.length >= minLength) {
+ if (minLength == 1) "`$name` must be non-empty, but was empty"
+ else "`$name` must have at least length $minLength, but was ${it.length}"
+ }
+ }
+
+@JvmSynthetic
+internal fun checkMaxLength(name: String, value: String, maxLength: Int): String =
+ value.also {
+ check(it.length <= maxLength) {
+ "`$name` must have at most length $maxLength, but was ${it.length}"
+ }
+ }
+
+@JvmSynthetic
+internal fun checkJacksonVersionCompatibility() {
+ val incompatibleJacksonVersions =
+ RUNTIME_JACKSON_VERSIONS.mapNotNull {
+ val badVersionReason = BAD_JACKSON_VERSIONS[it.toString()]
+ when {
+ it.majorVersion != MINIMUM_JACKSON_VERSION.majorVersion ->
+ it to "incompatible major version"
+ it.minorVersion < MINIMUM_JACKSON_VERSION.minorVersion ->
+ it to "minor version too low"
+ it.minorVersion == MINIMUM_JACKSON_VERSION.minorVersion &&
+ it.patchLevel < MINIMUM_JACKSON_VERSION.patchLevel ->
+ it to "patch version too low"
+ badVersionReason != null -> it to badVersionReason
+ else -> null
+ }
+ }
+ check(incompatibleJacksonVersions.isEmpty()) {
+ """
+This SDK requires a minimum Jackson version of $MINIMUM_JACKSON_VERSION, but the following incompatible Jackson versions were detected at runtime:
+
+${incompatibleJacksonVersions.asSequence().map { (version, incompatibilityReason) ->
+ "- `${version.toFullString().replace("/", ":")}` ($incompatibilityReason)"
+}.joinToString("\n")}
+
+This can happen if you are either:
+1. Directly depending on different Jackson versions
+2. Depending on some library that depends on different Jackson versions, potentially transitively
+
+Double-check that you are depending on compatible Jackson versions.
+
+See https://www.github.com/trycourier/courier-java#jackson for more information.
+ """
+ .trimIndent()
+ }
+}
+
+private val MINIMUM_JACKSON_VERSION: Version = VersionUtil.parseVersion("2.13.4", null, null)
+private val BAD_JACKSON_VERSIONS: Map =
+ mapOf("2.18.1" to "due to https://github.com/FasterXML/jackson-databind/issues/4639")
+private val RUNTIME_JACKSON_VERSIONS: List =
+ listOf(
+ com.fasterxml.jackson.core.json.PackageVersion.VERSION,
+ com.fasterxml.jackson.databind.cfg.PackageVersion.VERSION,
+ com.fasterxml.jackson.datatype.jdk8.PackageVersion.VERSION,
+ com.fasterxml.jackson.datatype.jsr310.PackageVersion.VERSION,
+ com.fasterxml.jackson.module.kotlin.PackageVersion.VERSION,
+ )
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/ClientOptions.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/ClientOptions.kt
new file mode 100644
index 00000000..232898e7
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/ClientOptions.kt
@@ -0,0 +1,450 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.core
+
+import com.courier.api.core.http.Headers
+import com.courier.api.core.http.HttpClient
+import com.courier.api.core.http.PhantomReachableClosingHttpClient
+import com.courier.api.core.http.QueryParams
+import com.courier.api.core.http.RetryingHttpClient
+import com.fasterxml.jackson.databind.json.JsonMapper
+import java.time.Clock
+import java.time.Duration
+import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
+
+/** A class representing the SDK client configuration. */
+class ClientOptions
+private constructor(
+ private val originalHttpClient: HttpClient,
+ /**
+ * The HTTP client to use in the SDK.
+ *
+ * Use the one published in `courier-java-client-okhttp` or implement your own.
+ *
+ * This class takes ownership of the client and closes it when closed.
+ */
+ @get:JvmName("httpClient") val httpClient: HttpClient,
+ /**
+ * Whether to throw an exception if any of the Jackson versions detected at runtime are
+ * incompatible with the SDK's minimum supported Jackson version (2.13.4).
+ *
+ * Defaults to true. Use extreme caution when disabling this option. There is no guarantee that
+ * the SDK will work correctly when using an incompatible Jackson version.
+ */
+ @get:JvmName("checkJacksonVersionCompatibility") val checkJacksonVersionCompatibility: Boolean,
+ /**
+ * The Jackson JSON mapper to use for serializing and deserializing JSON.
+ *
+ * Defaults to [com.courier.api.core.jsonMapper]. The default is usually sufficient and rarely
+ * needs to be overridden.
+ */
+ @get:JvmName("jsonMapper") val jsonMapper: JsonMapper,
+ /**
+ * The interface to use for delaying execution, like during retries.
+ *
+ * This is primarily useful for using fake delays in tests.
+ *
+ * Defaults to real execution delays.
+ *
+ * This class takes ownership of the sleeper and closes it when closed.
+ */
+ @get:JvmName("sleeper") val sleeper: Sleeper,
+ /**
+ * The clock to use for operations that require timing, like retries.
+ *
+ * This is primarily useful for using a fake clock in tests.
+ *
+ * Defaults to [Clock.systemUTC].
+ */
+ @get:JvmName("clock") val clock: Clock,
+ private val baseUrl: String?,
+ /** Headers to send with the request. */
+ @get:JvmName("headers") val headers: Headers,
+ /** Query params to send with the request. */
+ @get:JvmName("queryParams") val queryParams: QueryParams,
+ /**
+ * Whether to call `validate` on every response before returning it.
+ *
+ * Defaults to false, which means the shape of the response will not be validated upfront.
+ * Instead, validation will only occur for the parts of the response that are accessed.
+ */
+ @get:JvmName("responseValidation") val responseValidation: Boolean,
+ /**
+ * Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
+ * retries.
+ *
+ * Defaults to [Timeout.default].
+ */
+ @get:JvmName("timeout") val timeout: Timeout,
+ /**
+ * The maximum number of times to retry failed requests, with a short exponential backoff
+ * between requests.
+ *
+ * Only the following error types are retried:
+ * - Connection errors (for example, due to a network connectivity problem)
+ * - 408 Request Timeout
+ * - 409 Conflict
+ * - 429 Rate Limit
+ * - 5xx Internal
+ *
+ * The API may also explicitly instruct the SDK to retry or not retry a request.
+ *
+ * Defaults to 2.
+ */
+ @get:JvmName("maxRetries") val maxRetries: Int,
+ @get:JvmName("apiKey") val apiKey: String,
+) {
+
+ init {
+ if (checkJacksonVersionCompatibility) {
+ checkJacksonVersionCompatibility()
+ }
+ }
+
+ /**
+ * The base URL to use for every request.
+ *
+ * Defaults to the production environment: `https://api.courier.com`.
+ */
+ fun baseUrl(): String = baseUrl ?: PRODUCTION_URL
+
+ fun toBuilder() = Builder().from(this)
+
+ companion object {
+
+ const val PRODUCTION_URL = "https://api.courier.com"
+
+ /**
+ * Returns a mutable builder for constructing an instance of [ClientOptions].
+ *
+ * The following fields are required:
+ * ```java
+ * .httpClient()
+ * .apiKey()
+ * ```
+ */
+ @JvmStatic fun builder() = Builder()
+
+ /**
+ * Returns options configured using system properties and environment variables.
+ *
+ * @see Builder.fromEnv
+ */
+ @JvmStatic fun fromEnv(): ClientOptions = builder().fromEnv().build()
+ }
+
+ /** A builder for [ClientOptions]. */
+ class Builder internal constructor() {
+
+ private var httpClient: HttpClient? = null
+ private var checkJacksonVersionCompatibility: Boolean = true
+ private var jsonMapper: JsonMapper = jsonMapper()
+ private var sleeper: Sleeper? = null
+ private var clock: Clock = Clock.systemUTC()
+ private var baseUrl: String? = null
+ private var headers: Headers.Builder = Headers.builder()
+ private var queryParams: QueryParams.Builder = QueryParams.builder()
+ private var responseValidation: Boolean = false
+ private var timeout: Timeout = Timeout.default()
+ private var maxRetries: Int = 2
+ private var apiKey: String? = null
+
+ @JvmSynthetic
+ internal fun from(clientOptions: ClientOptions) = apply {
+ httpClient = clientOptions.originalHttpClient
+ checkJacksonVersionCompatibility = clientOptions.checkJacksonVersionCompatibility
+ jsonMapper = clientOptions.jsonMapper
+ sleeper = clientOptions.sleeper
+ clock = clientOptions.clock
+ baseUrl = clientOptions.baseUrl
+ headers = clientOptions.headers.toBuilder()
+ queryParams = clientOptions.queryParams.toBuilder()
+ responseValidation = clientOptions.responseValidation
+ timeout = clientOptions.timeout
+ maxRetries = clientOptions.maxRetries
+ apiKey = clientOptions.apiKey
+ }
+
+ /**
+ * The HTTP client to use in the SDK.
+ *
+ * Use the one published in `courier-java-client-okhttp` or implement your own.
+ *
+ * This class takes ownership of the client and closes it when closed.
+ */
+ fun httpClient(httpClient: HttpClient) = apply {
+ this.httpClient = PhantomReachableClosingHttpClient(httpClient)
+ }
+
+ /**
+ * Whether to throw an exception if any of the Jackson versions detected at runtime are
+ * incompatible with the SDK's minimum supported Jackson version (2.13.4).
+ *
+ * Defaults to true. Use extreme caution when disabling this option. There is no guarantee
+ * that the SDK will work correctly when using an incompatible Jackson version.
+ */
+ fun checkJacksonVersionCompatibility(checkJacksonVersionCompatibility: Boolean) = apply {
+ this.checkJacksonVersionCompatibility = checkJacksonVersionCompatibility
+ }
+
+ /**
+ * The Jackson JSON mapper to use for serializing and deserializing JSON.
+ *
+ * Defaults to [com.courier.api.core.jsonMapper]. The default is usually sufficient and
+ * rarely needs to be overridden.
+ */
+ fun jsonMapper(jsonMapper: JsonMapper) = apply { this.jsonMapper = jsonMapper }
+
+ /**
+ * The interface to use for delaying execution, like during retries.
+ *
+ * This is primarily useful for using fake delays in tests.
+ *
+ * Defaults to real execution delays.
+ *
+ * This class takes ownership of the sleeper and closes it when closed.
+ */
+ fun sleeper(sleeper: Sleeper) = apply { this.sleeper = PhantomReachableSleeper(sleeper) }
+
+ /**
+ * The clock to use for operations that require timing, like retries.
+ *
+ * This is primarily useful for using a fake clock in tests.
+ *
+ * Defaults to [Clock.systemUTC].
+ */
+ fun clock(clock: Clock) = apply { this.clock = clock }
+
+ /**
+ * The base URL to use for every request.
+ *
+ * Defaults to the production environment: `https://api.courier.com`.
+ */
+ fun baseUrl(baseUrl: String?) = apply { this.baseUrl = baseUrl }
+
+ /** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
+ fun baseUrl(baseUrl: Optional) = baseUrl(baseUrl.getOrNull())
+
+ /**
+ * Whether to call `validate` on every response before returning it.
+ *
+ * Defaults to false, which means the shape of the response will not be validated upfront.
+ * Instead, validation will only occur for the parts of the response that are accessed.
+ */
+ fun responseValidation(responseValidation: Boolean) = apply {
+ this.responseValidation = responseValidation
+ }
+
+ /**
+ * Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
+ * retries.
+ *
+ * Defaults to [Timeout.default].
+ */
+ fun timeout(timeout: Timeout) = apply { this.timeout = timeout }
+
+ /**
+ * Sets the maximum time allowed for a complete HTTP call, not including retries.
+ *
+ * See [Timeout.request] for more details.
+ *
+ * For fine-grained control, pass a [Timeout] object.
+ */
+ fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
+
+ /**
+ * The maximum number of times to retry failed requests, with a short exponential backoff
+ * between requests.
+ *
+ * Only the following error types are retried:
+ * - Connection errors (for example, due to a network connectivity problem)
+ * - 408 Request Timeout
+ * - 409 Conflict
+ * - 429 Rate Limit
+ * - 5xx Internal
+ *
+ * The API may also explicitly instruct the SDK to retry or not retry a request.
+ *
+ * Defaults to 2.
+ */
+ fun maxRetries(maxRetries: Int) = apply { this.maxRetries = maxRetries }
+
+ fun apiKey(apiKey: String) = apply { this.apiKey = apiKey }
+
+ fun headers(headers: Headers) = apply {
+ this.headers.clear()
+ putAllHeaders(headers)
+ }
+
+ fun headers(headers: Map>) = apply {
+ this.headers.clear()
+ putAllHeaders(headers)
+ }
+
+ fun putHeader(name: String, value: String) = apply { headers.put(name, value) }
+
+ fun putHeaders(name: String, values: Iterable) = apply { headers.put(name, values) }
+
+ fun putAllHeaders(headers: Headers) = apply { this.headers.putAll(headers) }
+
+ fun putAllHeaders(headers: Map>) = apply {
+ this.headers.putAll(headers)
+ }
+
+ fun replaceHeaders(name: String, value: String) = apply { headers.replace(name, value) }
+
+ fun replaceHeaders(name: String, values: Iterable) = apply {
+ headers.replace(name, values)
+ }
+
+ fun replaceAllHeaders(headers: Headers) = apply { this.headers.replaceAll(headers) }
+
+ fun replaceAllHeaders(headers: Map>) = apply {
+ this.headers.replaceAll(headers)
+ }
+
+ fun removeHeaders(name: String) = apply { headers.remove(name) }
+
+ fun removeAllHeaders(names: Set) = apply { headers.removeAll(names) }
+
+ fun queryParams(queryParams: QueryParams) = apply {
+ this.queryParams.clear()
+ putAllQueryParams(queryParams)
+ }
+
+ fun queryParams(queryParams: Map>) = apply {
+ this.queryParams.clear()
+ putAllQueryParams(queryParams)
+ }
+
+ fun putQueryParam(key: String, value: String) = apply { queryParams.put(key, value) }
+
+ fun putQueryParams(key: String, values: Iterable) = apply {
+ queryParams.put(key, values)
+ }
+
+ fun putAllQueryParams(queryParams: QueryParams) = apply {
+ this.queryParams.putAll(queryParams)
+ }
+
+ fun putAllQueryParams(queryParams: Map>) = apply {
+ this.queryParams.putAll(queryParams)
+ }
+
+ fun replaceQueryParams(key: String, value: String) = apply {
+ queryParams.replace(key, value)
+ }
+
+ fun replaceQueryParams(key: String, values: Iterable) = apply {
+ queryParams.replace(key, values)
+ }
+
+ fun replaceAllQueryParams(queryParams: QueryParams) = apply {
+ this.queryParams.replaceAll(queryParams)
+ }
+
+ fun replaceAllQueryParams(queryParams: Map>) = apply {
+ this.queryParams.replaceAll(queryParams)
+ }
+
+ fun removeQueryParams(key: String) = apply { queryParams.remove(key) }
+
+ fun removeAllQueryParams(keys: Set) = apply { queryParams.removeAll(keys) }
+
+ fun timeout(): Timeout = timeout
+
+ /**
+ * Updates configuration using system properties and environment variables.
+ *
+ * See this table for the available options:
+ *
+ * |Setter |System property |Environment variable|Required|Default value |
+ * |---------|-----------------|--------------------|--------|---------------------------|
+ * |`apiKey` |`courier.apiKey` |`COURIER_API_KEY` |true |- |
+ * |`baseUrl`|`courier.baseUrl`|`COURIER_BASE_URL` |true |`"https://api.courier.com"`|
+ *
+ * System properties take precedence over environment variables.
+ */
+ fun fromEnv() = apply {
+ (System.getProperty("courier.baseUrl") ?: System.getenv("COURIER_BASE_URL"))?.let {
+ baseUrl(it)
+ }
+ (System.getProperty("courier.apiKey") ?: System.getenv("COURIER_API_KEY"))?.let {
+ apiKey(it)
+ }
+ }
+
+ /**
+ * Returns an immutable instance of [ClientOptions].
+ *
+ * Further updates to this [Builder] will not mutate the returned instance.
+ *
+ * The following fields are required:
+ * ```java
+ * .httpClient()
+ * .apiKey()
+ * ```
+ *
+ * @throws IllegalStateException if any required field is unset.
+ */
+ fun build(): ClientOptions {
+ val httpClient = checkRequired("httpClient", httpClient)
+ val sleeper = sleeper ?: PhantomReachableSleeper(DefaultSleeper())
+ val apiKey = checkRequired("apiKey", apiKey)
+
+ val headers = Headers.builder()
+ val queryParams = QueryParams.builder()
+ headers.put("X-Stainless-Lang", "java")
+ headers.put("X-Stainless-Arch", getOsArch())
+ headers.put("X-Stainless-OS", getOsName())
+ headers.put("X-Stainless-OS-Version", getOsVersion())
+ headers.put("X-Stainless-Package-Version", getPackageVersion())
+ headers.put("X-Stainless-Runtime", "JRE")
+ headers.put("X-Stainless-Runtime-Version", getJavaVersion())
+ apiKey.let {
+ if (!it.isEmpty()) {
+ headers.put("Authorization", "Bearer $it")
+ }
+ }
+ headers.replaceAll(this.headers.build())
+ queryParams.replaceAll(this.queryParams.build())
+
+ return ClientOptions(
+ httpClient,
+ RetryingHttpClient.builder()
+ .httpClient(httpClient)
+ .sleeper(sleeper)
+ .clock(clock)
+ .maxRetries(maxRetries)
+ .build(),
+ checkJacksonVersionCompatibility,
+ jsonMapper,
+ sleeper,
+ clock,
+ baseUrl,
+ headers.build(),
+ queryParams.build(),
+ responseValidation,
+ timeout,
+ maxRetries,
+ apiKey,
+ )
+ }
+ }
+
+ /**
+ * Closes these client options, relinquishing any underlying resources.
+ *
+ * This is purposefully not inherited from [AutoCloseable] because the client options are
+ * long-lived and usually should not be synchronously closed via try-with-resources.
+ *
+ * It's also usually not necessary to call this method at all. the default client automatically
+ * releases threads and connections if they remain idle, but if you are writing an application
+ * that needs to aggressively release unused resources, then you may call this method.
+ */
+ fun close() {
+ httpClient.close()
+ sleeper.close()
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/DefaultSleeper.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/DefaultSleeper.kt
new file mode 100644
index 00000000..e068e204
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/DefaultSleeper.kt
@@ -0,0 +1,28 @@
+package com.courier.api.core
+
+import java.time.Duration
+import java.util.Timer
+import java.util.TimerTask
+import java.util.concurrent.CompletableFuture
+
+class DefaultSleeper : Sleeper {
+
+ private val timer = Timer("DefaultSleeper", true)
+
+ override fun sleep(duration: Duration) = Thread.sleep(duration.toMillis())
+
+ override fun sleepAsync(duration: Duration): CompletableFuture {
+ val future = CompletableFuture()
+ timer.schedule(
+ object : TimerTask() {
+ override fun run() {
+ future.complete(null)
+ }
+ },
+ duration.toMillis(),
+ )
+ return future
+ }
+
+ override fun close() = timer.cancel()
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/ObjectMappers.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/ObjectMappers.kt
new file mode 100644
index 00000000..5cfc46de
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/ObjectMappers.kt
@@ -0,0 +1,167 @@
+@file:JvmName("ObjectMappers")
+
+package com.courier.api.core
+
+import com.fasterxml.jackson.annotation.JsonInclude
+import com.fasterxml.jackson.core.JsonGenerator
+import com.fasterxml.jackson.core.JsonParseException
+import com.fasterxml.jackson.core.JsonParser
+import com.fasterxml.jackson.databind.DeserializationContext
+import com.fasterxml.jackson.databind.DeserializationFeature
+import com.fasterxml.jackson.databind.MapperFeature
+import com.fasterxml.jackson.databind.SerializationFeature
+import com.fasterxml.jackson.databind.SerializerProvider
+import com.fasterxml.jackson.databind.cfg.CoercionAction
+import com.fasterxml.jackson.databind.cfg.CoercionInputShape
+import com.fasterxml.jackson.databind.deser.std.StdDeserializer
+import com.fasterxml.jackson.databind.json.JsonMapper
+import com.fasterxml.jackson.databind.module.SimpleModule
+import com.fasterxml.jackson.databind.type.LogicalType
+import com.fasterxml.jackson.datatype.jdk8.Jdk8Module
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule
+import com.fasterxml.jackson.module.kotlin.kotlinModule
+import java.io.InputStream
+import java.time.DateTimeException
+import java.time.LocalDate
+import java.time.LocalDateTime
+import java.time.ZonedDateTime
+import java.time.format.DateTimeFormatter
+import java.time.temporal.ChronoField
+
+fun jsonMapper(): JsonMapper =
+ JsonMapper.builder()
+ .addModule(kotlinModule())
+ .addModule(Jdk8Module())
+ .addModule(JavaTimeModule())
+ .addModule(
+ SimpleModule()
+ .addSerializer(InputStreamSerializer)
+ .addDeserializer(LocalDateTime::class.java, LenientLocalDateTimeDeserializer())
+ )
+ .withCoercionConfig(LogicalType.Boolean) {
+ it.setCoercion(CoercionInputShape.Integer, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Float, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.String, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Array, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Object, CoercionAction.Fail)
+ }
+ .withCoercionConfig(LogicalType.Integer) {
+ it.setCoercion(CoercionInputShape.Boolean, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.String, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Array, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Object, CoercionAction.Fail)
+ }
+ .withCoercionConfig(LogicalType.Float) {
+ it.setCoercion(CoercionInputShape.Boolean, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.String, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Array, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Object, CoercionAction.Fail)
+ }
+ .withCoercionConfig(LogicalType.Textual) {
+ it.setCoercion(CoercionInputShape.Boolean, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Integer, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Float, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Array, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Object, CoercionAction.Fail)
+ }
+ .withCoercionConfig(LogicalType.Array) {
+ it.setCoercion(CoercionInputShape.Boolean, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Integer, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Float, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.String, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Object, CoercionAction.Fail)
+ }
+ .withCoercionConfig(LogicalType.Collection) {
+ it.setCoercion(CoercionInputShape.Boolean, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Integer, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Float, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.String, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Object, CoercionAction.Fail)
+ }
+ .withCoercionConfig(LogicalType.Map) {
+ it.setCoercion(CoercionInputShape.Boolean, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Integer, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Float, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.String, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Object, CoercionAction.Fail)
+ }
+ .withCoercionConfig(LogicalType.POJO) {
+ it.setCoercion(CoercionInputShape.Boolean, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Integer, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Float, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.String, CoercionAction.Fail)
+ .setCoercion(CoercionInputShape.Array, CoercionAction.Fail)
+ }
+ .serializationInclusion(JsonInclude.Include.NON_ABSENT)
+ .disable(DeserializationFeature.ADJUST_DATES_TO_CONTEXT_TIME_ZONE)
+ .disable(SerializationFeature.FLUSH_AFTER_WRITE_VALUE)
+ .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+ .disable(SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS)
+ .disable(MapperFeature.ALLOW_COERCION_OF_SCALARS)
+ .disable(MapperFeature.AUTO_DETECT_CREATORS)
+ .disable(MapperFeature.AUTO_DETECT_FIELDS)
+ .disable(MapperFeature.AUTO_DETECT_GETTERS)
+ .disable(MapperFeature.AUTO_DETECT_IS_GETTERS)
+ .disable(MapperFeature.AUTO_DETECT_SETTERS)
+ .build()
+
+/** A serializer that serializes [InputStream] to bytes. */
+private object InputStreamSerializer : BaseSerializer(InputStream::class) {
+
+ private fun readResolve(): Any = InputStreamSerializer
+
+ override fun serialize(
+ value: InputStream?,
+ gen: JsonGenerator?,
+ serializers: SerializerProvider?,
+ ) {
+ if (value == null) {
+ gen?.writeNull()
+ } else {
+ value.use { gen?.writeBinary(it.readBytes()) }
+ }
+ }
+}
+
+/**
+ * A deserializer that can deserialize [LocalDateTime] from datetimes, dates, and zoned datetimes.
+ */
+private class LenientLocalDateTimeDeserializer :
+ StdDeserializer(LocalDateTime::class.java) {
+
+ companion object {
+
+ private val DATE_TIME_FORMATTERS =
+ listOf(
+ DateTimeFormatter.ISO_LOCAL_DATE_TIME,
+ DateTimeFormatter.ISO_LOCAL_DATE,
+ DateTimeFormatter.ISO_ZONED_DATE_TIME,
+ )
+ }
+
+ override fun logicalType(): LogicalType = LogicalType.DateTime
+
+ override fun deserialize(p: JsonParser, context: DeserializationContext?): LocalDateTime {
+ val exceptions = mutableListOf()
+
+ for (formatter in DATE_TIME_FORMATTERS) {
+ try {
+ val temporal = formatter.parse(p.text)
+
+ return when {
+ !temporal.isSupported(ChronoField.HOUR_OF_DAY) ->
+ LocalDate.from(temporal).atStartOfDay()
+ !temporal.isSupported(ChronoField.OFFSET_SECONDS) ->
+ LocalDateTime.from(temporal)
+ else -> ZonedDateTime.from(temporal).toLocalDateTime()
+ }
+ } catch (e: DateTimeException) {
+ exceptions.add(e)
+ }
+ }
+
+ throw JsonParseException(p, "Cannot parse `LocalDateTime` from value: ${p.text}").apply {
+ exceptions.forEach { addSuppressed(it) }
+ }
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/Params.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/Params.kt
new file mode 100644
index 00000000..a04c55b9
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/Params.kt
@@ -0,0 +1,16 @@
+package com.courier.api.core
+
+import com.courier.api.core.http.Headers
+import com.courier.api.core.http.QueryParams
+
+/** An interface representing parameters passed to a service method. */
+interface Params {
+ /** The full set of headers in the parameters, including both fixed and additional headers. */
+ fun _headers(): Headers
+
+ /**
+ * The full set of query params in the parameters, including both fixed and additional query
+ * params.
+ */
+ fun _queryParams(): QueryParams
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachable.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachable.kt
new file mode 100644
index 00000000..42ae140e
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachable.kt
@@ -0,0 +1,56 @@
+@file:JvmName("PhantomReachable")
+
+package com.courier.api.core
+
+import com.courier.api.errors.CourierException
+import java.lang.reflect.InvocationTargetException
+
+/**
+ * Closes [closeable] when [observed] becomes only phantom reachable.
+ *
+ * This is a wrapper around a Java 9+ [java.lang.ref.Cleaner], or a no-op in older Java versions.
+ */
+@JvmSynthetic
+internal fun closeWhenPhantomReachable(observed: Any, closeable: AutoCloseable) {
+ check(observed !== closeable) {
+ "`observed` cannot be the same object as `closeable` because it would never become phantom reachable"
+ }
+ closeWhenPhantomReachable(observed, closeable::close)
+}
+
+/**
+ * Calls [close] when [observed] becomes only phantom reachable.
+ *
+ * This is a wrapper around a Java 9+ [java.lang.ref.Cleaner], or a no-op in older Java versions.
+ */
+@JvmSynthetic
+internal fun closeWhenPhantomReachable(observed: Any, close: () -> Unit) {
+ closeWhenPhantomReachable?.let { it(observed, close) }
+}
+
+private val closeWhenPhantomReachable: ((Any, () -> Unit) -> Unit)? by lazy {
+ try {
+ val cleanerClass = Class.forName("java.lang.ref.Cleaner")
+ val cleanerCreate = cleanerClass.getMethod("create")
+ val cleanerRegister =
+ cleanerClass.getMethod("register", Any::class.java, Runnable::class.java)
+ val cleanerObject = cleanerCreate.invoke(null);
+
+ { observed, close ->
+ try {
+ cleanerRegister.invoke(cleanerObject, observed, Runnable { close() })
+ } catch (e: ReflectiveOperationException) {
+ if (e is InvocationTargetException) {
+ when (val cause = e.cause) {
+ is RuntimeException,
+ is Error -> throw cause
+ }
+ }
+ throw CourierException("Unexpected reflective invocation failure", e)
+ }
+ }
+ } catch (e: ReflectiveOperationException) {
+ // We're running Java 8, which has no Cleaner.
+ null
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachableExecutorService.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachableExecutorService.kt
new file mode 100644
index 00000000..20e6c410
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachableExecutorService.kt
@@ -0,0 +1,58 @@
+package com.courier.api.core
+
+import java.util.concurrent.Callable
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Future
+import java.util.concurrent.TimeUnit
+
+/**
+ * A delegating wrapper around an [ExecutorService] that shuts it down once it's only phantom
+ * reachable.
+ *
+ * This class ensures the [ExecutorService] is shut down even if the user forgets to do it.
+ */
+internal class PhantomReachableExecutorService(private val executorService: ExecutorService) :
+ ExecutorService {
+ init {
+ closeWhenPhantomReachable(this) { executorService.shutdown() }
+ }
+
+ override fun execute(command: Runnable) = executorService.execute(command)
+
+ override fun shutdown() = executorService.shutdown()
+
+ override fun shutdownNow(): MutableList = executorService.shutdownNow()
+
+ override fun isShutdown(): Boolean = executorService.isShutdown
+
+ override fun isTerminated(): Boolean = executorService.isTerminated
+
+ override fun awaitTermination(timeout: Long, unit: TimeUnit): Boolean =
+ executorService.awaitTermination(timeout, unit)
+
+ override fun submit(task: Callable): Future = executorService.submit(task)
+
+ override fun submit(task: Runnable, result: T): Future =
+ executorService.submit(task, result)
+
+ override fun submit(task: Runnable): Future<*> = executorService.submit(task)
+
+ override fun invokeAll(
+ tasks: MutableCollection>
+ ): MutableList> = executorService.invokeAll(tasks)
+
+ override fun invokeAll(
+ tasks: MutableCollection>,
+ timeout: Long,
+ unit: TimeUnit,
+ ): MutableList> = executorService.invokeAll(tasks, timeout, unit)
+
+ override fun invokeAny(tasks: MutableCollection>): T =
+ executorService.invokeAny(tasks)
+
+ override fun invokeAny(
+ tasks: MutableCollection>,
+ timeout: Long,
+ unit: TimeUnit,
+ ): T = executorService.invokeAny(tasks, timeout, unit)
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachableSleeper.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachableSleeper.kt
new file mode 100644
index 00000000..6af9d159
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/PhantomReachableSleeper.kt
@@ -0,0 +1,23 @@
+package com.courier.api.core
+
+import java.time.Duration
+import java.util.concurrent.CompletableFuture
+
+/**
+ * A delegating wrapper around a [Sleeper] that closes it once it's only phantom reachable.
+ *
+ * This class ensures the [Sleeper] is closed even if the user forgets to do it.
+ */
+internal class PhantomReachableSleeper(private val sleeper: Sleeper) : Sleeper {
+
+ init {
+ closeWhenPhantomReachable(this, sleeper)
+ }
+
+ override fun sleep(duration: Duration) = sleeper.sleep(duration)
+
+ override fun sleepAsync(duration: Duration): CompletableFuture =
+ sleeper.sleepAsync(duration)
+
+ override fun close() = sleeper.close()
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/PrepareRequest.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/PrepareRequest.kt
new file mode 100644
index 00000000..0864d52b
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/PrepareRequest.kt
@@ -0,0 +1,24 @@
+@file:JvmName("PrepareRequest")
+
+package com.courier.api.core
+
+import com.courier.api.core.http.HttpRequest
+import java.util.concurrent.CompletableFuture
+
+@JvmSynthetic
+internal fun HttpRequest.prepare(clientOptions: ClientOptions, params: Params): HttpRequest =
+ toBuilder()
+ .putAllQueryParams(clientOptions.queryParams)
+ .replaceAllQueryParams(params._queryParams())
+ .putAllHeaders(clientOptions.headers)
+ .replaceAllHeaders(params._headers())
+ .build()
+
+@JvmSynthetic
+internal fun HttpRequest.prepareAsync(
+ clientOptions: ClientOptions,
+ params: Params,
+): CompletableFuture =
+ // This async version exists to make it easier to add async specific preparation logic in the
+ // future.
+ CompletableFuture.completedFuture(prepare(clientOptions, params))
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/Properties.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/Properties.kt
new file mode 100644
index 00000000..e2c8c5f6
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/Properties.kt
@@ -0,0 +1,42 @@
+@file:JvmName("Properties")
+
+package com.courier.api.core
+
+import com.courier.api.client.CourierClient
+
+fun getOsArch(): String {
+ val osArch = System.getProperty("os.arch")
+
+ return when (osArch) {
+ null -> "unknown"
+ "i386",
+ "x32",
+ "x86" -> "x32"
+ "amd64",
+ "x86_64" -> "x64"
+ "arm" -> "arm"
+ "aarch64" -> "arm64"
+ else -> "other:$osArch"
+ }
+}
+
+fun getOsName(): String {
+ val osName = System.getProperty("os.name")
+ val vendorUrl = System.getProperty("java.vendor.url")
+
+ return when {
+ osName == null -> "Unknown"
+ osName.startsWith("Linux") && vendorUrl == "http://www.android.com/" -> "Android"
+ osName.startsWith("Linux") -> "Linux"
+ osName.startsWith("Mac OS") -> "MacOS"
+ osName.startsWith("Windows") -> "Windows"
+ else -> "Other:$osName"
+ }
+}
+
+fun getOsVersion(): String = System.getProperty("os.version", "unknown")
+
+fun getPackageVersion(): String =
+ CourierClient::class.java.`package`.implementationVersion ?: "unknown"
+
+fun getJavaVersion(): String = System.getProperty("java.version", "unknown")
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/RequestOptions.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/RequestOptions.kt
new file mode 100644
index 00000000..40194eea
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/RequestOptions.kt
@@ -0,0 +1,46 @@
+package com.courier.api.core
+
+import java.time.Duration
+
+class RequestOptions private constructor(val responseValidation: Boolean?, val timeout: Timeout?) {
+
+ companion object {
+
+ private val NONE = builder().build()
+
+ @JvmStatic fun none() = NONE
+
+ @JvmSynthetic
+ internal fun from(clientOptions: ClientOptions): RequestOptions =
+ builder()
+ .responseValidation(clientOptions.responseValidation)
+ .timeout(clientOptions.timeout)
+ .build()
+
+ @JvmStatic fun builder() = Builder()
+ }
+
+ fun applyDefaults(options: RequestOptions): RequestOptions =
+ RequestOptions(
+ responseValidation = responseValidation ?: options.responseValidation,
+ timeout =
+ if (options.timeout != null && timeout != null) timeout.assign(options.timeout)
+ else timeout ?: options.timeout,
+ )
+
+ class Builder internal constructor() {
+
+ private var responseValidation: Boolean? = null
+ private var timeout: Timeout? = null
+
+ fun responseValidation(responseValidation: Boolean) = apply {
+ this.responseValidation = responseValidation
+ }
+
+ fun timeout(timeout: Timeout) = apply { this.timeout = timeout }
+
+ fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
+
+ fun build(): RequestOptions = RequestOptions(responseValidation, timeout)
+ }
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/Sleeper.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/Sleeper.kt
new file mode 100644
index 00000000..3289f942
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/Sleeper.kt
@@ -0,0 +1,21 @@
+package com.courier.api.core
+
+import java.time.Duration
+import java.util.concurrent.CompletableFuture
+
+/**
+ * An interface for delaying execution for a specified amount of time.
+ *
+ * Useful for testing and cleaning up resources.
+ */
+interface Sleeper : AutoCloseable {
+
+ /** Synchronously pauses execution for the given [duration]. */
+ fun sleep(duration: Duration)
+
+ /** Asynchronously pauses execution for the given [duration]. */
+ fun sleepAsync(duration: Duration): CompletableFuture
+
+ /** Overridden from [AutoCloseable] to not have a checked exception in its signature. */
+ override fun close()
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/Timeout.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/Timeout.kt
new file mode 100644
index 00000000..614a6434
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/Timeout.kt
@@ -0,0 +1,171 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.core
+
+import java.time.Duration
+import java.util.Objects
+import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
+
+/** A class containing timeouts for various processing phases of a request. */
+class Timeout
+private constructor(
+ private val connect: Duration?,
+ private val read: Duration?,
+ private val write: Duration?,
+ private val request: Duration?,
+) {
+
+ /**
+ * The maximum time allowed to establish a connection with a host.
+ *
+ * A value of [Duration.ZERO] means there's no timeout.
+ *
+ * Defaults to `Duration.ofMinutes(1)`.
+ */
+ fun connect(): Duration = connect ?: Duration.ofMinutes(1)
+
+ /**
+ * The maximum time allowed between two data packets when waiting for the server’s response.
+ *
+ * A value of [Duration.ZERO] means there's no timeout.
+ *
+ * Defaults to `request()`.
+ */
+ fun read(): Duration = read ?: request()
+
+ /**
+ * The maximum time allowed between two data packets when sending the request to the server.
+ *
+ * A value of [Duration.ZERO] means there's no timeout.
+ *
+ * Defaults to `request()`.
+ */
+ fun write(): Duration = write ?: request()
+
+ /**
+ * The maximum time allowed for a complete HTTP call, not including retries.
+ *
+ * This includes resolving DNS, connecting, writing the request body, server processing, as well
+ * as reading the response body.
+ *
+ * A value of [Duration.ZERO] means there's no timeout.
+ *
+ * Defaults to `Duration.ofMinutes(1)`.
+ */
+ fun request(): Duration = request ?: Duration.ofMinutes(1)
+
+ fun toBuilder() = Builder().from(this)
+
+ companion object {
+
+ @JvmStatic fun default() = builder().build()
+
+ /** Returns a mutable builder for constructing an instance of [Timeout]. */
+ @JvmStatic fun builder() = Builder()
+ }
+
+ /** A builder for [Timeout]. */
+ class Builder internal constructor() {
+
+ private var connect: Duration? = null
+ private var read: Duration? = null
+ private var write: Duration? = null
+ private var request: Duration? = null
+
+ @JvmSynthetic
+ internal fun from(timeout: Timeout) = apply {
+ connect = timeout.connect
+ read = timeout.read
+ write = timeout.write
+ request = timeout.request
+ }
+
+ /**
+ * The maximum time allowed to establish a connection with a host.
+ *
+ * A value of [Duration.ZERO] means there's no timeout.
+ *
+ * Defaults to `Duration.ofMinutes(1)`.
+ */
+ fun connect(connect: Duration?) = apply { this.connect = connect }
+
+ /** Alias for calling [Builder.connect] with `connect.orElse(null)`. */
+ fun connect(connect: Optional) = connect(connect.getOrNull())
+
+ /**
+ * The maximum time allowed between two data packets when waiting for the server’s response.
+ *
+ * A value of [Duration.ZERO] means there's no timeout.
+ *
+ * Defaults to `request()`.
+ */
+ fun read(read: Duration?) = apply { this.read = read }
+
+ /** Alias for calling [Builder.read] with `read.orElse(null)`. */
+ fun read(read: Optional) = read(read.getOrNull())
+
+ /**
+ * The maximum time allowed between two data packets when sending the request to the server.
+ *
+ * A value of [Duration.ZERO] means there's no timeout.
+ *
+ * Defaults to `request()`.
+ */
+ fun write(write: Duration?) = apply { this.write = write }
+
+ /** Alias for calling [Builder.write] with `write.orElse(null)`. */
+ fun write(write: Optional) = write(write.getOrNull())
+
+ /**
+ * The maximum time allowed for a complete HTTP call, not including retries.
+ *
+ * This includes resolving DNS, connecting, writing the request body, server processing, as
+ * well as reading the response body.
+ *
+ * A value of [Duration.ZERO] means there's no timeout.
+ *
+ * Defaults to `Duration.ofMinutes(1)`.
+ */
+ fun request(request: Duration?) = apply { this.request = request }
+
+ /** Alias for calling [Builder.request] with `request.orElse(null)`. */
+ fun request(request: Optional) = request(request.getOrNull())
+
+ /**
+ * Returns an immutable instance of [Timeout].
+ *
+ * Further updates to this [Builder] will not mutate the returned instance.
+ */
+ fun build(): Timeout = Timeout(connect, read, write, request)
+ }
+
+ @JvmSynthetic
+ internal fun assign(target: Timeout): Timeout =
+ target
+ .toBuilder()
+ .apply {
+ connect?.let(this::connect)
+ read?.let(this::read)
+ write?.let(this::write)
+ request?.let(this::request)
+ }
+ .build()
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is Timeout &&
+ connect == other.connect &&
+ read == other.read &&
+ write == other.write &&
+ request == other.request
+ }
+
+ override fun hashCode(): Int = Objects.hash(connect, read, write, request)
+
+ override fun toString() =
+ "Timeout{connect=$connect, read=$read, write=$write, request=$request}"
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/Utils.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/Utils.kt
new file mode 100644
index 00000000..cac76471
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/Utils.kt
@@ -0,0 +1,115 @@
+@file:JvmName("Utils")
+
+package com.courier.api.core
+
+import com.courier.api.errors.CourierInvalidDataException
+import java.util.Collections
+import java.util.SortedMap
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.locks.Lock
+
+@JvmSynthetic
+internal fun T?.getOrThrow(name: String): T =
+ this ?: throw CourierInvalidDataException("`${name}` is not present")
+
+@JvmSynthetic
+internal fun List.toImmutable(): List =
+ if (isEmpty()) Collections.emptyList() else Collections.unmodifiableList(toList())
+
+@JvmSynthetic
+internal fun Map.toImmutable(): Map =
+ if (isEmpty()) immutableEmptyMap() else Collections.unmodifiableMap(toMap())
+
+@JvmSynthetic internal fun immutableEmptyMap(): Map = Collections.emptyMap()
+
+@JvmSynthetic
+internal fun , V> SortedMap.toImmutable(): SortedMap =
+ if (isEmpty()) Collections.emptySortedMap()
+ else Collections.unmodifiableSortedMap(toSortedMap(comparator()))
+
+/**
+ * Returns all elements that yield the largest value for the given function, or an empty list if
+ * there are zero elements.
+ *
+ * This is similar to [Sequence.maxByOrNull] except it returns _all_ elements that yield the largest
+ * value; not just the first one.
+ */
+@JvmSynthetic
+internal fun > Sequence.allMaxBy(selector: (T) -> R): List {
+ var maxValue: R? = null
+ val maxElements = mutableListOf()
+
+ val iterator = iterator()
+ while (iterator.hasNext()) {
+ val element = iterator.next()
+ val value = selector(element)
+ if (maxValue == null || value > maxValue) {
+ maxValue = value
+ maxElements.clear()
+ maxElements.add(element)
+ } else if (value == maxValue) {
+ maxElements.add(element)
+ }
+ }
+
+ return maxElements
+}
+
+/**
+ * Returns whether [this] is equal to [other].
+ *
+ * This differs from [Object.equals] because it also deeply equates arrays based on their contents,
+ * even when there are arrays directly nested within other arrays.
+ */
+@JvmSynthetic
+internal infix fun Any?.contentEquals(other: Any?): Boolean =
+ arrayOf(this).contentDeepEquals(arrayOf(other))
+
+/**
+ * Returns a hash of the given sequence of [values].
+ *
+ * This differs from [java.util.Objects.hash] because it also deeply hashes arrays based on their
+ * contents, even when there are arrays directly nested within other arrays.
+ */
+@JvmSynthetic internal fun contentHash(vararg values: Any?): Int = values.contentDeepHashCode()
+
+/**
+ * Returns a [String] representation of [this].
+ *
+ * This differs from [Object.toString] because it also deeply stringifies arrays based on their
+ * contents, even when there are arrays directly nested within other arrays.
+ */
+@JvmSynthetic
+internal fun Any?.contentToString(): String {
+ var string = arrayOf(this).contentDeepToString()
+ if (string.startsWith('[')) {
+ string = string.substring(1)
+ }
+ if (string.endsWith(']')) {
+ string = string.substring(0, string.length - 1)
+ }
+ return string
+}
+
+internal interface Enum
+
+/**
+ * Executes the given [action] while holding the lock, returning a [CompletableFuture] with the
+ * result.
+ *
+ * @param action The asynchronous action to execute while holding the lock
+ * @return A [CompletableFuture] that completes with the result of the action
+ */
+@JvmSynthetic
+internal fun Lock.withLockAsync(action: () -> CompletableFuture): CompletableFuture {
+ lock()
+ val future =
+ try {
+ action()
+ } catch (e: Throwable) {
+ unlock()
+ throw e
+ }
+ future.whenComplete { _, _ -> unlock() }
+ return future
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/Values.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/Values.kt
new file mode 100644
index 00000000..4017bb76
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/Values.kt
@@ -0,0 +1,723 @@
+package com.courier.api.core
+
+import com.courier.api.errors.CourierInvalidDataException
+import com.fasterxml.jackson.annotation.JacksonAnnotationsInside
+import com.fasterxml.jackson.annotation.JsonCreator
+import com.fasterxml.jackson.annotation.JsonInclude
+import com.fasterxml.jackson.core.JsonGenerator
+import com.fasterxml.jackson.core.ObjectCodec
+import com.fasterxml.jackson.core.type.TypeReference
+import com.fasterxml.jackson.databind.BeanProperty
+import com.fasterxml.jackson.databind.DeserializationContext
+import com.fasterxml.jackson.databind.JavaType
+import com.fasterxml.jackson.databind.JsonDeserializer
+import com.fasterxml.jackson.databind.JsonNode
+import com.fasterxml.jackson.databind.SerializerProvider
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize
+import com.fasterxml.jackson.databind.annotation.JsonSerialize
+import com.fasterxml.jackson.databind.node.JsonNodeType.ARRAY
+import com.fasterxml.jackson.databind.node.JsonNodeType.BINARY
+import com.fasterxml.jackson.databind.node.JsonNodeType.BOOLEAN
+import com.fasterxml.jackson.databind.node.JsonNodeType.MISSING
+import com.fasterxml.jackson.databind.node.JsonNodeType.NULL
+import com.fasterxml.jackson.databind.node.JsonNodeType.NUMBER
+import com.fasterxml.jackson.databind.node.JsonNodeType.OBJECT
+import com.fasterxml.jackson.databind.node.JsonNodeType.POJO
+import com.fasterxml.jackson.databind.node.JsonNodeType.STRING
+import com.fasterxml.jackson.databind.ser.std.NullSerializer
+import java.io.InputStream
+import java.util.Objects
+import java.util.Optional
+
+/**
+ * A class representing a serializable JSON field.
+ *
+ * It can either be a [KnownValue] value of type [T], matching the type the SDK expects, or an
+ * arbitrary JSON value that bypasses the type system (via [JsonValue]).
+ */
+@JsonDeserialize(using = JsonField.Deserializer::class)
+sealed class JsonField {
+
+ /**
+ * Returns whether this field is missing, which means it will be omitted from the serialized
+ * JSON entirely.
+ */
+ fun isMissing(): Boolean = this is JsonMissing
+
+ /** Whether this field is explicitly set to `null`. */
+ fun isNull(): Boolean = this is JsonNull
+
+ /**
+ * Returns an [Optional] containing this field's "known" value, meaning it matches the type the
+ * SDK expects, or an empty [Optional] if this field contains an arbitrary [JsonValue].
+ *
+ * This is the opposite of [asUnknown].
+ */
+ fun asKnown():
+ Optional<
+ // Safe because `Optional` is effectively covariant, but Kotlin doesn't know that.
+ @UnsafeVariance
+ T
+ > = Optional.ofNullable((this as? KnownValue)?.value)
+
+ /**
+ * Returns an [Optional] containing this field's arbitrary [JsonValue], meaning it mismatches
+ * the type the SDK expects, or an empty [Optional] if this field contains a "known" value.
+ *
+ * This is the opposite of [asKnown].
+ */
+ fun asUnknown(): Optional = Optional.ofNullable(this as? JsonValue)
+
+ /**
+ * Returns an [Optional] containing this field's boolean value, or an empty [Optional] if it
+ * doesn't contain a boolean.
+ *
+ * This method checks for both a [KnownValue] containing a boolean and for [JsonBoolean].
+ */
+ fun asBoolean(): Optional =
+ when (this) {
+ is JsonBoolean -> Optional.of(value)
+ is KnownValue -> Optional.ofNullable(value as? Boolean)
+ else -> Optional.empty()
+ }
+
+ /**
+ * Returns an [Optional] containing this field's numerical value, or an empty [Optional] if it
+ * doesn't contain a number.
+ *
+ * This method checks for both a [KnownValue] containing a number and for [JsonNumber].
+ */
+ fun asNumber(): Optional =
+ when (this) {
+ is JsonNumber -> Optional.of(value)
+ is KnownValue -> Optional.ofNullable(value as? Number)
+ else -> Optional.empty()
+ }
+
+ /**
+ * Returns an [Optional] containing this field's string value, or an empty [Optional] if it
+ * doesn't contain a string.
+ *
+ * This method checks for both a [KnownValue] containing a string and for [JsonString].
+ */
+ fun asString(): Optional =
+ when (this) {
+ is JsonString -> Optional.of(value)
+ is KnownValue -> Optional.ofNullable(value as? String)
+ else -> Optional.empty()
+ }
+
+ fun asStringOrThrow(): String =
+ asString().orElseThrow { CourierInvalidDataException("Value is not a string") }
+
+ /**
+ * Returns an [Optional] containing this field's list value, or an empty [Optional] if it
+ * doesn't contain a list.
+ *
+ * This method checks for both a [KnownValue] containing a list and for [JsonArray].
+ */
+ fun asArray(): Optional> =
+ when (this) {
+ is JsonArray -> Optional.of(values)
+ is KnownValue ->
+ Optional.ofNullable(
+ (value as? List<*>)?.map {
+ try {
+ JsonValue.from(it)
+ } catch (e: IllegalArgumentException) {
+ // The known value is a list, but not all values are convertible to
+ // `JsonValue`.
+ return Optional.empty()
+ }
+ }
+ )
+ else -> Optional.empty()
+ }
+
+ /**
+ * Returns an [Optional] containing this field's map value, or an empty [Optional] if it doesn't
+ * contain a map.
+ *
+ * This method checks for both a [KnownValue] containing a map and for [JsonObject].
+ */
+ fun asObject(): Optional> =
+ when (this) {
+ is JsonObject -> Optional.of(values)
+ is KnownValue ->
+ Optional.ofNullable(
+ (value as? Map<*, *>)
+ ?.map { (key, value) ->
+ if (key !is String) {
+ return Optional.empty()
+ }
+
+ val jsonValue =
+ try {
+ JsonValue.from(value)
+ } catch (e: IllegalArgumentException) {
+ // The known value is a map, but not all items are convertible
+ // to `JsonValue`.
+ return Optional.empty()
+ }
+
+ key to jsonValue
+ }
+ ?.toMap()
+ )
+ else -> Optional.empty()
+ }
+
+ @JvmSynthetic
+ internal fun getRequired(name: String): T =
+ when (this) {
+ is KnownValue -> value
+ is JsonMissing -> throw CourierInvalidDataException("`$name` is not set")
+ is JsonNull -> throw CourierInvalidDataException("`$name` is null")
+ else -> throw CourierInvalidDataException("`$name` is invalid, received $this")
+ }
+
+ @JvmSynthetic
+ internal fun getOptional(
+ name: String
+ ): Optional<
+ // Safe because `Optional` is effectively covariant, but Kotlin doesn't know that.
+ @UnsafeVariance
+ T
+ > =
+ when (this) {
+ is KnownValue -> Optional.of(value)
+ is JsonMissing,
+ is JsonNull -> Optional.empty()
+ else -> throw CourierInvalidDataException("`$name` is invalid, received $this")
+ }
+
+ @JvmSynthetic
+ internal fun map(transform: (T) -> R): JsonField =
+ when (this) {
+ is KnownValue -> KnownValue.of(transform(value))
+ is JsonValue -> this
+ }
+
+ @JvmSynthetic internal fun accept(consume: (T) -> Unit) = asKnown().ifPresent(consume)
+
+ /** Returns the result of calling the [visitor] method corresponding to this field's state. */
+ fun accept(visitor: Visitor): R =
+ when (this) {
+ is KnownValue -> visitor.visitKnown(value)
+ is JsonValue -> accept(visitor as JsonValue.Visitor)
+ }
+
+ /**
+ * An interface that defines how to map each possible state of a `JsonField` to a value of
+ * type [R].
+ */
+ interface Visitor : JsonValue.Visitor {
+
+ fun visitKnown(value: T): R = visitDefault()
+ }
+
+ companion object {
+
+ /** Returns a [JsonField] containing the given "known" [value]. */
+ @JvmStatic fun of(value: T): JsonField = KnownValue.of(value)
+
+ /**
+ * Returns a [JsonField] containing the given "known" [value], or [JsonNull] if [value] is
+ * null.
+ */
+ @JvmStatic
+ fun ofNullable(value: T?): JsonField =
+ when (value) {
+ null -> JsonNull.of()
+ else -> KnownValue.of(value)
+ }
+ }
+
+ /**
+ * This class is a Jackson filter that can be used to exclude missing properties from objects.
+ * This filter should not be used directly and should instead use the @ExcludeMissing
+ * annotation.
+ */
+ class IsMissing {
+
+ override fun equals(other: Any?): Boolean = other is JsonMissing
+
+ override fun hashCode(): Int = Objects.hash()
+ }
+
+ class Deserializer(private val type: JavaType? = null) :
+ BaseDeserializer>(JsonField::class) {
+
+ override fun createContextual(
+ context: DeserializationContext,
+ property: BeanProperty?,
+ ): JsonDeserializer> = Deserializer(context.contextualType?.containedType(0))
+
+ override fun ObjectCodec.deserialize(node: JsonNode): JsonField<*> =
+ type?.let { tryDeserialize(node, type) }?.let { of(it) }
+ ?: JsonValue.fromJsonNode(node)
+
+ override fun getNullValue(context: DeserializationContext): JsonField<*> = JsonNull.of()
+ }
+}
+
+/**
+ * A class representing an arbitrary JSON value.
+ *
+ * It is immutable and assignable to any [JsonField], regardless of its expected type (i.e. its
+ * generic type argument).
+ */
+@JsonDeserialize(using = JsonValue.Deserializer::class)
+sealed class JsonValue : JsonField() {
+
+ fun convert(type: TypeReference): R? = JSON_MAPPER.convertValue(this, type)
+
+ fun convert(type: Class): R? = JSON_MAPPER.convertValue(this, type)
+
+ /** Returns the result of calling the [visitor] method corresponding to this value's variant. */
+ fun accept(visitor: Visitor): R =
+ when (this) {
+ is JsonMissing -> visitor.visitMissing()
+ is JsonNull -> visitor.visitNull()
+ is JsonBoolean -> visitor.visitBoolean(value)
+ is JsonNumber -> visitor.visitNumber(value)
+ is JsonString -> visitor.visitString(value)
+ is JsonArray -> visitor.visitArray(values)
+ is JsonObject -> visitor.visitObject(values)
+ }
+
+ /**
+ * An interface that defines how to map each variant state of a [JsonValue] to a value of type
+ * [R].
+ */
+ interface Visitor {
+
+ fun visitNull(): R = visitDefault()
+
+ fun visitMissing(): R = visitDefault()
+
+ fun visitBoolean(value: Boolean): R = visitDefault()
+
+ fun visitNumber(value: Number): R = visitDefault()
+
+ fun visitString(value: String): R = visitDefault()
+
+ fun visitArray(values: List): R = visitDefault()
+
+ fun visitObject(values: Map): R = visitDefault()
+
+ /**
+ * The default implementation for unimplemented visitor methods.
+ *
+ * @throws IllegalArgumentException in the default implementation.
+ */
+ fun visitDefault(): R = throw IllegalArgumentException("Unexpected value")
+ }
+
+ companion object {
+
+ private val JSON_MAPPER = jsonMapper()
+
+ /**
+ * Converts the given [value] to a [JsonValue].
+ *
+ * This method works best on primitive types, [List] values, [Map] values, and nested
+ * combinations of these. For example:
+ * ```java
+ * // Create primitive JSON values
+ * JsonValue nullValue = JsonValue.from(null);
+ * JsonValue booleanValue = JsonValue.from(true);
+ * JsonValue numberValue = JsonValue.from(42);
+ * JsonValue stringValue = JsonValue.from("Hello World!");
+ *
+ * // Create a JSON array value equivalent to `["Hello", "World"]`
+ * JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));
+ *
+ * // Create a JSON object value equivalent to `{ "a": 1, "b": 2 }`
+ * JsonValue objectValue = JsonValue.from(Map.of(
+ * "a", 1,
+ * "b", 2
+ * ));
+ *
+ * // Create an arbitrarily nested JSON equivalent to:
+ * // {
+ * // "a": [1, 2],
+ * // "b": [3, 4]
+ * // }
+ * JsonValue complexValue = JsonValue.from(Map.of(
+ * "a", List.of(1, 2),
+ * "b", List.of(3, 4)
+ * ));
+ * ```
+ *
+ * @throws IllegalArgumentException if [value] is not JSON serializable.
+ */
+ @JvmStatic
+ fun from(value: Any?): JsonValue =
+ when (value) {
+ null -> JsonNull.of()
+ is JsonValue -> value
+ else -> JSON_MAPPER.convertValue(value, JsonValue::class.java)
+ }
+
+ /**
+ * Returns a [JsonValue] converted from the given Jackson [JsonNode].
+ *
+ * @throws IllegalStateException for unsupported node types.
+ */
+ @JvmStatic
+ fun fromJsonNode(node: JsonNode): JsonValue =
+ when (node.nodeType) {
+ MISSING -> JsonMissing.of()
+ NULL -> JsonNull.of()
+ BOOLEAN -> JsonBoolean.of(node.booleanValue())
+ NUMBER -> JsonNumber.of(node.numberValue())
+ STRING -> JsonString.of(node.textValue())
+ ARRAY ->
+ JsonArray.of(node.elements().asSequence().map { fromJsonNode(it) }.toList())
+ OBJECT ->
+ JsonObject.of(
+ node.fields().asSequence().map { it.key to fromJsonNode(it.value) }.toMap()
+ )
+ BINARY,
+ POJO,
+ null -> throw IllegalStateException("Unexpected JsonNode type: ${node.nodeType}")
+ }
+ }
+
+ class Deserializer : BaseDeserializer(JsonValue::class) {
+
+ override fun ObjectCodec.deserialize(node: JsonNode): JsonValue = fromJsonNode(node)
+
+ override fun getNullValue(context: DeserializationContext?): JsonValue = JsonNull.of()
+ }
+}
+
+/**
+ * A class representing a "known" JSON serializable value of type [T], matching the type the SDK
+ * expects.
+ *
+ * It is assignable to `JsonField`.
+ */
+class KnownValue
+private constructor(
+ @com.fasterxml.jackson.annotation.JsonValue @get:JvmName("value") val value: T
+) : JsonField() {
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is KnownValue<*> && value contentEquals other.value
+ }
+
+ override fun hashCode() = contentHash(value)
+
+ override fun toString() = value.contentToString()
+
+ companion object {
+
+ /** Returns a [KnownValue] containing the given [value]. */
+ @JsonCreator @JvmStatic fun of(value: T) = KnownValue(value)
+ }
+}
+
+/**
+ * A [JsonValue] representing an omitted JSON field.
+ *
+ * An instance of this class will cause a JSON field to be omitted from the serialized JSON
+ * entirely.
+ */
+@JsonSerialize(using = JsonMissing.Serializer::class)
+class JsonMissing : JsonValue() {
+
+ override fun toString() = ""
+
+ companion object {
+
+ private val INSTANCE: JsonMissing = JsonMissing()
+
+ /** Returns the singleton instance of [JsonMissing]. */
+ @JvmStatic fun of() = INSTANCE
+ }
+
+ class Serializer : BaseSerializer(JsonMissing::class) {
+
+ override fun serialize(
+ value: JsonMissing,
+ generator: JsonGenerator,
+ provider: SerializerProvider,
+ ) {
+ throw IllegalStateException("JsonMissing cannot be serialized")
+ }
+ }
+}
+
+/** A [JsonValue] representing a JSON `null` value. */
+@JsonSerialize(using = NullSerializer::class)
+class JsonNull : JsonValue() {
+
+ override fun toString() = "null"
+
+ companion object {
+
+ private val INSTANCE: JsonNull = JsonNull()
+
+ /** Returns the singleton instance of [JsonMissing]. */
+ @JsonCreator @JvmStatic fun of() = INSTANCE
+ }
+}
+
+/** A [JsonValue] representing a JSON boolean value. */
+class JsonBoolean
+private constructor(
+ @get:com.fasterxml.jackson.annotation.JsonValue @get:JvmName("value") val value: Boolean
+) : JsonValue() {
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is JsonBoolean && value == other.value
+ }
+
+ override fun hashCode() = value.hashCode()
+
+ override fun toString() = value.toString()
+
+ companion object {
+
+ /** Returns a [JsonBoolean] containing the given [value]. */
+ @JsonCreator @JvmStatic fun of(value: Boolean) = JsonBoolean(value)
+ }
+}
+
+/** A [JsonValue] representing a JSON number value. */
+class JsonNumber
+private constructor(
+ @get:com.fasterxml.jackson.annotation.JsonValue @get:JvmName("value") val value: Number
+) : JsonValue() {
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is JsonNumber && value == other.value
+ }
+
+ override fun hashCode() = value.hashCode()
+
+ override fun toString() = value.toString()
+
+ companion object {
+
+ /** Returns a [JsonNumber] containing the given [value]. */
+ @JsonCreator @JvmStatic fun of(value: Number) = JsonNumber(value)
+ }
+}
+
+/** A [JsonValue] representing a JSON string value. */
+class JsonString
+private constructor(
+ @get:com.fasterxml.jackson.annotation.JsonValue @get:JvmName("value") val value: String
+) : JsonValue() {
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is JsonString && value == other.value
+ }
+
+ override fun hashCode() = value.hashCode()
+
+ override fun toString() = value
+
+ companion object {
+
+ /** Returns a [JsonString] containing the given [value]. */
+ @JsonCreator @JvmStatic fun of(value: String) = JsonString(value)
+ }
+}
+
+/** A [JsonValue] representing a JSON array value. */
+class JsonArray
+private constructor(
+ @get:com.fasterxml.jackson.annotation.JsonValue
+ @get:JvmName("values")
+ val values: List
+) : JsonValue() {
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is JsonArray && values == other.values
+ }
+
+ override fun hashCode() = values.hashCode()
+
+ override fun toString() = values.toString()
+
+ companion object {
+
+ /** Returns a [JsonArray] containing the given [values]. */
+ @JsonCreator @JvmStatic fun of(values: List) = JsonArray(values.toImmutable())
+ }
+}
+
+/** A [JsonValue] representing a JSON object value. */
+class JsonObject
+private constructor(
+ @get:com.fasterxml.jackson.annotation.JsonValue
+ @get:JvmName("values")
+ val values: Map
+) : JsonValue() {
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is JsonObject && values == other.values
+ }
+
+ override fun hashCode() = values.hashCode()
+
+ override fun toString() = values.toString()
+
+ companion object {
+
+ /** Returns a [JsonObject] containing the given [values]. */
+ @JsonCreator
+ @JvmStatic
+ fun of(values: Map) = JsonObject(values.toImmutable())
+ }
+}
+
+/** A Jackson annotation for excluding fields set to [JsonMissing] from the serialized JSON. */
+@JacksonAnnotationsInside
+@JsonInclude(JsonInclude.Include.CUSTOM, valueFilter = JsonField.IsMissing::class)
+annotation class ExcludeMissing
+
+/** A class representing a field in a `multipart/form-data` request. */
+class MultipartField
+private constructor(
+ /** A [JsonField] value, which will be serialized to zero or more parts. */
+ @get:com.fasterxml.jackson.annotation.JsonValue @get:JvmName("value") val value: JsonField,
+ /** A content type for the serialized parts. */
+ @get:JvmName("contentType") val contentType: String,
+ private val filename: String?,
+) {
+
+ companion object {
+
+ /**
+ * Returns a [MultipartField] containing the given [value] as a [KnownValue].
+ *
+ * [contentType] will be set to `application/octet-stream` if [value] is binary data, or
+ * `text/plain; charset=utf-8` otherwise.
+ */
+ @JvmStatic fun of(value: T?) = builder().value(value).build()
+
+ /**
+ * Returns a [MultipartField] containing the given [value].
+ *
+ * [contentType] will be set to `application/octet-stream` if [value] is binary data, or
+ * `text/plain; charset=utf-8` otherwise.
+ */
+ @JvmStatic fun of(value: JsonField) = builder().value(value).build()
+
+ /**
+ * Returns a mutable builder for constructing an instance of [MultipartField].
+ *
+ * The following fields are required:
+ * ```java
+ * .value()
+ * ```
+ *
+ * If [contentType] is unset, then it will be set to `application/octet-stream` if [value]
+ * is binary data, or `text/plain; charset=utf-8` otherwise.
+ */
+ @JvmStatic fun builder() = Builder()
+ }
+
+ /** Returns the filename directive that will be included in the serialized field. */
+ fun filename(): Optional = Optional.ofNullable(filename)
+
+ @JvmSynthetic
+ internal fun map(transform: (T) -> R): MultipartField =
+ builder().value(value.map(transform)).contentType(contentType).filename(filename).build()
+
+ /** A builder for [MultipartField]. */
+ class Builder internal constructor() {
+
+ private var value: JsonField? = null
+ private var contentType: String? = null
+ private var filename: String? = null
+
+ fun value(value: JsonField) = apply { this.value = value }
+
+ fun value(value: T?) = value(JsonField.ofNullable(value))
+
+ fun contentType(contentType: String) = apply { this.contentType = contentType }
+
+ fun filename(filename: String?) = apply { this.filename = filename }
+
+ /** Alias for calling [Builder.filename] with `filename.orElse(null)`. */
+ fun filename(filename: Optional) = filename(filename.orElse(null))
+
+ /**
+ * Returns an immutable instance of [MultipartField].
+ *
+ * Further updates to this [Builder] will not mutate the returned instance.
+ *
+ * The following fields are required:
+ * ```java
+ * .value()
+ * ```
+ *
+ * If [contentType] is unset, then it will be set to `application/octet-stream` if [value]
+ * is binary data, or `text/plain; charset=utf-8` otherwise.
+ *
+ * @throws IllegalStateException if any required field is unset.
+ */
+ fun build(): MultipartField {
+ val value = checkRequired("value", value)
+ return MultipartField(
+ value,
+ contentType
+ ?: if (
+ value is KnownValue &&
+ (value.value is InputStream || value.value is ByteArray)
+ )
+ "application/octet-stream"
+ else "text/plain; charset=utf-8",
+ filename,
+ )
+ }
+ }
+
+ private val hashCode: Int by lazy { contentHash(value, contentType, filename) }
+
+ override fun hashCode(): Int = hashCode
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is MultipartField<*> &&
+ value == other.value &&
+ contentType == other.contentType &&
+ filename == other.filename
+ }
+
+ override fun toString(): String =
+ "MultipartField{value=$value, contentType=$contentType, filename=$filename}"
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/EmptyHandler.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/EmptyHandler.kt
new file mode 100644
index 00000000..e4628b3a
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/EmptyHandler.kt
@@ -0,0 +1,12 @@
+@file:JvmName("EmptyHandler")
+
+package com.courier.api.core.handlers
+
+import com.courier.api.core.http.HttpResponse
+import com.courier.api.core.http.HttpResponse.Handler
+
+@JvmSynthetic internal fun emptyHandler(): Handler = EmptyHandlerInternal
+
+private object EmptyHandlerInternal : Handler {
+ override fun handle(response: HttpResponse): Void? = null
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/ErrorHandler.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/ErrorHandler.kt
new file mode 100644
index 00000000..111485ae
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/ErrorHandler.kt
@@ -0,0 +1,84 @@
+// File generated from our OpenAPI spec by Stainless.
+
+@file:JvmName("ErrorHandler")
+
+package com.courier.api.core.handlers
+
+import com.courier.api.core.JsonMissing
+import com.courier.api.core.JsonValue
+import com.courier.api.core.http.HttpResponse
+import com.courier.api.core.http.HttpResponse.Handler
+import com.courier.api.errors.BadRequestException
+import com.courier.api.errors.InternalServerException
+import com.courier.api.errors.NotFoundException
+import com.courier.api.errors.PermissionDeniedException
+import com.courier.api.errors.RateLimitException
+import com.courier.api.errors.UnauthorizedException
+import com.courier.api.errors.UnexpectedStatusCodeException
+import com.courier.api.errors.UnprocessableEntityException
+import com.fasterxml.jackson.databind.json.JsonMapper
+
+@JvmSynthetic
+internal fun errorBodyHandler(jsonMapper: JsonMapper): Handler {
+ val handler = jsonHandler(jsonMapper)
+
+ return object : Handler {
+ override fun handle(response: HttpResponse): JsonValue =
+ try {
+ handler.handle(response)
+ } catch (e: Exception) {
+ JsonMissing.of()
+ }
+ }
+}
+
+@JvmSynthetic
+internal fun errorHandler(errorBodyHandler: Handler): Handler =
+ object : Handler {
+ override fun handle(response: HttpResponse): HttpResponse =
+ when (val statusCode = response.statusCode()) {
+ in 200..299 -> response
+ 400 ->
+ throw BadRequestException.builder()
+ .headers(response.headers())
+ .body(errorBodyHandler.handle(response))
+ .build()
+ 401 ->
+ throw UnauthorizedException.builder()
+ .headers(response.headers())
+ .body(errorBodyHandler.handle(response))
+ .build()
+ 403 ->
+ throw PermissionDeniedException.builder()
+ .headers(response.headers())
+ .body(errorBodyHandler.handle(response))
+ .build()
+ 404 ->
+ throw NotFoundException.builder()
+ .headers(response.headers())
+ .body(errorBodyHandler.handle(response))
+ .build()
+ 422 ->
+ throw UnprocessableEntityException.builder()
+ .headers(response.headers())
+ .body(errorBodyHandler.handle(response))
+ .build()
+ 429 ->
+ throw RateLimitException.builder()
+ .headers(response.headers())
+ .body(errorBodyHandler.handle(response))
+ .build()
+ in 500..599 ->
+ throw InternalServerException.builder()
+ .statusCode(statusCode)
+ .headers(response.headers())
+ .body(errorBodyHandler.handle(response))
+ .build()
+ else ->
+ throw UnexpectedStatusCodeException.builder()
+ .statusCode(statusCode)
+ .headers(response.headers())
+ .body(errorBodyHandler.handle(response))
+ .build()
+ }
+ }
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/JsonHandler.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/JsonHandler.kt
new file mode 100644
index 00000000..ec50c983
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/JsonHandler.kt
@@ -0,0 +1,20 @@
+@file:JvmName("JsonHandler")
+
+package com.courier.api.core.handlers
+
+import com.courier.api.core.http.HttpResponse
+import com.courier.api.core.http.HttpResponse.Handler
+import com.courier.api.errors.CourierInvalidDataException
+import com.fasterxml.jackson.databind.json.JsonMapper
+import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
+
+@JvmSynthetic
+internal inline fun jsonHandler(jsonMapper: JsonMapper): Handler =
+ object : Handler {
+ override fun handle(response: HttpResponse): T =
+ try {
+ jsonMapper.readValue(response.body(), jacksonTypeRef())
+ } catch (e: Exception) {
+ throw CourierInvalidDataException("Error reading response", e)
+ }
+ }
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/StringHandler.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/StringHandler.kt
new file mode 100644
index 00000000..fb961c6b
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/handlers/StringHandler.kt
@@ -0,0 +1,13 @@
+@file:JvmName("StringHandler")
+
+package com.courier.api.core.handlers
+
+import com.courier.api.core.http.HttpResponse
+import com.courier.api.core.http.HttpResponse.Handler
+
+@JvmSynthetic internal fun stringHandler(): Handler = StringHandlerInternal
+
+private object StringHandlerInternal : Handler {
+ override fun handle(response: HttpResponse): String =
+ response.body().readBytes().toString(Charsets.UTF_8)
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/http/AsyncStreamResponse.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/http/AsyncStreamResponse.kt
new file mode 100644
index 00000000..8776a843
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/http/AsyncStreamResponse.kt
@@ -0,0 +1,157 @@
+package com.courier.api.core.http
+
+import com.courier.api.core.http.AsyncStreamResponse.Handler
+import java.util.Optional
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.Executor
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * A class providing access to an API response as an asynchronous stream of chunks of type [T],
+ * where each chunk can be individually processed as soon as it arrives instead of waiting on the
+ * full response.
+ */
+interface AsyncStreamResponse {
+
+ /**
+ * Registers [handler] to be called for events of this stream.
+ *
+ * [handler]'s methods will be called in the client's configured or default thread pool.
+ *
+ * @throws IllegalStateException if [subscribe] has already been called.
+ */
+ fun subscribe(handler: Handler): AsyncStreamResponse
+
+ /**
+ * Registers [handler] to be called for events of this stream.
+ *
+ * [handler]'s methods will be called in the given [executor].
+ *
+ * @throws IllegalStateException if [subscribe] has already been called.
+ */
+ fun subscribe(handler: Handler, executor: Executor): AsyncStreamResponse
+
+ /**
+ * Returns a future that completes when a stream is fully consumed, errors, or gets closed
+ * early.
+ */
+ fun onCompleteFuture(): CompletableFuture
+
+ /**
+ * Closes this resource, relinquishing any underlying resources.
+ *
+ * This is purposefully not inherited from [AutoCloseable] because this response should not be
+ * synchronously closed via try-with-resources.
+ */
+ fun close()
+
+ /** A class for handling streaming events. */
+ fun interface Handler {
+
+ /** Called whenever a chunk is received. */
+ fun onNext(value: T)
+
+ /**
+ * Called when a stream is fully consumed, errors, or gets closed early.
+ *
+ * [onNext] will not be called once this method is called.
+ *
+ * @param error Non-empty if the stream completed due to an error.
+ */
+ fun onComplete(error: Optional) {}
+ }
+}
+
+@JvmSynthetic
+internal fun CompletableFuture>.toAsync(streamHandlerExecutor: Executor) =
+ PhantomReachableClosingAsyncStreamResponse(
+ object : AsyncStreamResponse {
+
+ private val onCompleteFuture = CompletableFuture()
+ private val state = AtomicReference(State.NEW)
+
+ init {
+ this@toAsync.whenComplete { _, error ->
+ // If an error occurs from the original future, then we should resolve the
+ // `onCompleteFuture` even if `subscribe` has not been called.
+ error?.let(onCompleteFuture::completeExceptionally)
+ }
+ }
+
+ override fun subscribe(handler: Handler): AsyncStreamResponse =
+ subscribe(handler, streamHandlerExecutor)
+
+ override fun subscribe(
+ handler: Handler,
+ executor: Executor,
+ ): AsyncStreamResponse = apply {
+ // TODO(JDK): Use `compareAndExchange` once targeting JDK 9.
+ check(state.compareAndSet(State.NEW, State.SUBSCRIBED)) {
+ if (state.get() == State.SUBSCRIBED) "Cannot subscribe more than once"
+ else "Cannot subscribe after the response is closed"
+ }
+
+ this@toAsync.whenCompleteAsync(
+ { streamResponse, futureError ->
+ if (state.get() == State.CLOSED) {
+ // Avoid doing any work if `close` was called before the future
+ // completed.
+ return@whenCompleteAsync
+ }
+
+ if (futureError != null) {
+ // An error occurred before we started passing chunks to the handler.
+ handler.onComplete(Optional.of(futureError))
+ return@whenCompleteAsync
+ }
+
+ var streamError: Throwable? = null
+ try {
+ streamResponse.stream().forEach(handler::onNext)
+ } catch (e: Throwable) {
+ streamError = e
+ }
+
+ try {
+ handler.onComplete(Optional.ofNullable(streamError))
+ } finally {
+ try {
+ // Notify completion via the `onCompleteFuture` as well. This is in
+ // a separate `try-finally` block so that we still complete the
+ // future if `handler.onComplete` throws.
+ if (streamError == null) {
+ onCompleteFuture.complete(null)
+ } else {
+ onCompleteFuture.completeExceptionally(streamError)
+ }
+ } finally {
+ close()
+ }
+ }
+ },
+ executor,
+ )
+ }
+
+ override fun onCompleteFuture(): CompletableFuture = onCompleteFuture
+
+ override fun close() {
+ val previousState = state.getAndSet(State.CLOSED)
+ if (previousState == State.CLOSED) {
+ return
+ }
+
+ this@toAsync.whenComplete { streamResponse, error -> streamResponse?.close() }
+ // When the stream is closed, we should always consider it closed. If it closed due
+ // to an error, then we will have already completed the future earlier, and this
+ // will be a no-op.
+ onCompleteFuture.complete(null)
+ }
+ }
+ )
+
+private enum class State {
+ NEW,
+ SUBSCRIBED,
+ CLOSED,
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/http/Headers.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/http/Headers.kt
new file mode 100644
index 00000000..38cb1932
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/http/Headers.kt
@@ -0,0 +1,115 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.courier.api.core.http
+
+import com.courier.api.core.JsonArray
+import com.courier.api.core.JsonBoolean
+import com.courier.api.core.JsonMissing
+import com.courier.api.core.JsonNull
+import com.courier.api.core.JsonNumber
+import com.courier.api.core.JsonObject
+import com.courier.api.core.JsonString
+import com.courier.api.core.JsonValue
+import com.courier.api.core.toImmutable
+import java.util.TreeMap
+
+class Headers
+private constructor(
+ private val map: Map>,
+ @get:JvmName("size") val size: Int,
+) {
+
+ fun isEmpty(): Boolean = map.isEmpty()
+
+ fun names(): Set = map.keys
+
+ fun values(name: String): List = map[name].orEmpty()
+
+ fun toBuilder(): Builder = Builder().putAll(map)
+
+ companion object {
+
+ @JvmStatic fun builder() = Builder()
+ }
+
+ class Builder internal constructor() {
+
+ private val map: MutableMap> =
+ TreeMap(String.CASE_INSENSITIVE_ORDER)
+ private var size: Int = 0
+
+ fun put(name: String, value: JsonValue): Builder = apply {
+ when (value) {
+ is JsonMissing,
+ is JsonNull -> {}
+ is JsonBoolean -> put(name, value.value.toString())
+ is JsonNumber -> put(name, value.value.toString())
+ is JsonString -> put(name, value.value)
+ is JsonArray -> value.values.forEach { put(name, it) }
+ is JsonObject ->
+ value.values.forEach { (nestedName, value) -> put("$name.$nestedName", value) }
+ }
+ }
+
+ fun put(name: String, value: String) = apply {
+ map.getOrPut(name) { mutableListOf() }.add(value)
+ size++
+ }
+
+ fun put(name: String, values: Iterable) = apply { values.forEach { put(name, it) } }
+
+ fun putAll(headers: Map>) = apply { headers.forEach(::put) }
+
+ fun putAll(headers: Headers) = apply {
+ headers.names().forEach { put(it, headers.values(it)) }
+ }
+
+ fun replace(name: String, value: String) = apply {
+ remove(name)
+ put(name, value)
+ }
+
+ fun replace(name: String, values: Iterable) = apply {
+ remove(name)
+ put(name, values)
+ }
+
+ fun replaceAll(headers: Map>) = apply {
+ headers.forEach(::replace)
+ }
+
+ fun replaceAll(headers: Headers) = apply {
+ headers.names().forEach { replace(it, headers.values(it)) }
+ }
+
+ fun remove(name: String) = apply { size -= map.remove(name).orEmpty().size }
+
+ fun removeAll(names: Set) = apply { names.forEach(::remove) }
+
+ fun clear() = apply {
+ map.clear()
+ size = 0
+ }
+
+ fun build() =
+ Headers(
+ map.mapValuesTo(TreeMap(String.CASE_INSENSITIVE_ORDER)) { (_, values) ->
+ values.toImmutable()
+ }
+ .toImmutable(),
+ size,
+ )
+ }
+
+ override fun hashCode(): Int = map.hashCode()
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) {
+ return true
+ }
+
+ return other is Headers && map == other.map
+ }
+
+ override fun toString(): String = "Headers{map=$map}"
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpClient.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpClient.kt
new file mode 100644
index 00000000..edf43271
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpClient.kt
@@ -0,0 +1,26 @@
+package com.courier.api.core.http
+
+import com.courier.api.core.RequestOptions
+import java.lang.AutoCloseable
+import java.util.concurrent.CompletableFuture
+
+interface HttpClient : AutoCloseable {
+
+ fun execute(
+ request: HttpRequest,
+ requestOptions: RequestOptions = RequestOptions.none(),
+ ): HttpResponse
+
+ fun execute(request: HttpRequest): HttpResponse = execute(request, RequestOptions.none())
+
+ fun executeAsync(
+ request: HttpRequest,
+ requestOptions: RequestOptions = RequestOptions.none(),
+ ): CompletableFuture
+
+ fun executeAsync(request: HttpRequest): CompletableFuture =
+ executeAsync(request, RequestOptions.none())
+
+ /** Overridden from [AutoCloseable] to not have a checked exception in its signature. */
+ override fun close()
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpMethod.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpMethod.kt
new file mode 100644
index 00000000..bee49976
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpMethod.kt
@@ -0,0 +1,13 @@
+package com.courier.api.core.http
+
+enum class HttpMethod {
+ GET,
+ HEAD,
+ POST,
+ PUT,
+ DELETE,
+ CONNECT,
+ OPTIONS,
+ TRACE,
+ PATCH,
+}
diff --git a/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpRequest.kt b/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpRequest.kt
new file mode 100644
index 00000000..f9459ab0
--- /dev/null
+++ b/courier-java-core/src/main/kotlin/com/courier/api/core/http/HttpRequest.kt
@@ -0,0 +1,146 @@
+package com.courier.api.core.http
+
+import com.courier.api.core.checkRequired
+import com.courier.api.core.toImmutable
+
+class HttpRequest
+private constructor(
+ @get:JvmName("method") val method: HttpMethod,
+ @get:JvmName("baseUrl") val baseUrl: String,
+ @get:JvmName("pathSegments") val pathSegments: List,
+ @get:JvmName("headers") val headers: Headers,
+ @get:JvmName("queryParams") val queryParams: QueryParams,
+ @get:JvmName("body") val body: HttpRequestBody?,
+) {
+
+ fun toBuilder(): Builder = Builder().from(this)
+
+ override fun toString(): String =
+ "HttpRequest{method=$method, baseUrl=$baseUrl, pathSegments=$pathSegments, headers=$headers, queryParams=$queryParams, body=$body}"
+
+ companion object {
+ @JvmStatic fun builder() = Builder()
+ }
+
+ class Builder internal constructor() {
+
+ private var method: HttpMethod? = null
+ private var baseUrl: String? = null
+ private var pathSegments: MutableList = mutableListOf()
+ private var headers: Headers.Builder = Headers.builder()
+ private var queryParams: QueryParams.Builder = QueryParams.builder()
+ private var body: HttpRequestBody? = null
+
+ @JvmSynthetic
+ internal fun from(request: HttpRequest) = apply {
+ method = request.method
+ baseUrl = request.baseUrl
+ pathSegments = request.pathSegments.toMutableList()
+ headers = request.headers.toBuilder()
+ queryParams = request.queryParams.toBuilder()
+ body = request.body
+ }
+
+ fun method(method: HttpMethod) = apply { this.method = method }
+
+ fun baseUrl(baseUrl: String) = apply { this.baseUrl = baseUrl }
+
+ fun addPathSegment(pathSegment: String) = apply { pathSegments.add(pathSegment) }
+
+ fun addPathSegments(vararg pathSegments: String) = apply {
+ this.pathSegments.addAll(pathSegments)
+ }
+
+ fun headers(headers: Headers) = apply {
+ this.headers.clear()
+ putAllHeaders(headers)
+ }
+
+ fun headers(headers: Map>) = apply {
+ this.headers.clear()
+ putAllHeaders(headers)
+ }
+
+ fun putHeader(name: String, value: String) = apply { headers.put(name, value) }
+
+ fun putHeaders(name: String, values: Iterable) = apply { headers.put(name, values) }
+
+ fun putAllHeaders(headers: Headers) = apply { this.headers.putAll(headers) }
+
+ fun putAllHeaders(headers: Map>) = apply {
+ this.headers.putAll(headers)
+ }
+
+ fun replaceHeaders(name: String, value: String) = apply { headers.replace(name, value) }
+
+ fun replaceHeaders(name: String, values: Iterable) = apply {
+ headers.replace(name, values)
+ }
+
+ fun replaceAllHeaders(headers: Headers) = apply { this.headers.replaceAll(headers) }
+
+ fun replaceAllHeaders(headers: Map>) = apply {
+ this.headers.replaceAll(headers)
+ }
+
+ fun removeHeaders(name: String) = apply { headers.remove(name) }
+
+ fun removeAllHeaders(names: Set) = apply { headers.removeAll(names) }
+
+ fun queryParams(queryParams: QueryParams) = apply {
+ this.queryParams.clear()
+ putAllQueryParams(queryParams)
+ }
+
+ fun queryParams(queryParams: Map>) = apply {
+ this.queryParams.clear()
+ putAllQueryParams(queryParams)
+ }
+
+ fun putQueryParam(key: String, value: String) = apply { queryParams.put(key, value) }
+
+ fun putQueryParams(key: String, values: Iterable) = apply {
+ queryParams.put(key, values)
+ }
+
+ fun putAllQueryParams(queryParams: QueryParams) = apply {
+ this.queryParams.putAll(queryParams)
+ }
+
+ fun putAllQueryParams(queryParams: Map>) = apply {
+ this.queryParams.putAll(queryParams)
+ }
+
+ fun replaceQueryParams(key: String, value: String) = apply {
+ queryParams.replace(key, value)
+ }
+
+ fun replaceQueryParams(key: String, values: Iterable) = apply {
+ queryParams.replace(key, values)
+ }
+
+ fun replaceAllQueryParams(queryParams: QueryParams) = apply {
+ this.queryParams.replaceAll(queryParams)
+ }
+
+ fun replaceAllQueryParams(queryParams: Map