diff --git a/.fernignore b/.fernignore index 3aa9b05..e3c9019 100644 --- a/.fernignore +++ b/.fernignore @@ -90,3 +90,6 @@ src/main/resources/META-INF/proguard/whop-java.pro .github/public-maven.py .github/test_public_maven.py INSTALL.md + +# Hand-written quick start. Remove when Fern emits this format with verified install steps. +README.md diff --git a/README.md b/README.md index 75b9f00..4fed7b5 100644 --- a/README.md +++ b/README.md @@ -1,245 +1,57 @@ -# Whop Java Library +# Whop Java SDK -[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=Whop%2FJava) +Call the Whop API from Java or Android. -The Whop SDK gives you typed access to the Whop API. Pass your API key to the client explicitly — the SDK reads no environment variables, so a client built without a key sends unauthenticated requests and the API answers 401. +## Install +Use Java 8 or later. Add this repository to `settings.gradle.kts`: -## Table of Contents - -- [Documentation](#documentation) -- [Reference](#reference) -- [Usage](#usage) -- [Environments](#environments) -- [Base Url](#base-url) -- [Exception Handling](#exception-handling) -- [Advanced](#advanced) - - [Custom Client](#custom-client) - - [Retries](#retries) - - [Timeouts](#timeouts) - - [Custom Headers](#custom-headers) - - [Additional Body Properties](#additional-body-properties) - - [Access Raw Response Data](#access-raw-response-data) -- [Contributing](#contributing) - -## Documentation - -API reference documentation is available [here](https://docs.whop.com/api-reference). - -## Reference - -A full reference for this library is available [here](./reference.md). - -## Installation - -See [INSTALL.md](INSTALL.md) for public Gradle, Android, and Maven installation instructions. - -## Usage - -Instantiate and use the client with the following: - -```java -package com.example.usage; - -import com.whop.api.WhopApiClient; -import com.whop.api.resources.accesstokens.requests.CreateAccessTokensRequest; - -public class Example { - public static void main(String[] args) { - WhopApiClient client = WhopApiClient - .builder() - .token("") - .build(); - - client.accessTokens().create( - CreateAccessTokensRequest - .builder() - .build() - ); +```kotlin +dependencyResolutionManagement { + repositories { + google() + mavenCentral() + maven { + url = uri("https://whopio.github.io/whopsdk-java/") + content { includeGroup("com.whop.api") } + } } } ``` -## Environments - -This SDK allows you to configure different environments for API requests. - -```java -import com.whop.api.WhopApiClient; -import com.whop.api.core.Environment; - -WhopApiClient client = WhopApiClient - .builder() - .environment(Environment.PRODUCTION) - .build(); -``` - -## Base Url - -You can set a custom base URL when constructing the client. - -```java -import com.whop.api.WhopApiClient; - -WhopApiClient client = WhopApiClient - .builder() - .url("https://example.com") - .build(); -``` - -## Exception Handling - -When the API returns a non-success status code (4xx or 5xx response), an API exception will be thrown. +Add this dependency to your app: -```java -import com.whop.api.core.WhopApiApiException; - -try{ - client.accessTokens().create(...); -} catch (WhopApiApiException e){ - // Do something with the API exception... +```kotlin +dependencies { + implementation("com.whop.api:whop-java:2.8.1") } ``` -## Advanced - -### Custom Client +## Read products -This SDK is built to work with any instance of `OkHttpClient`. By default, if no client is provided, the SDK will construct one. -However, you can pass your own client like so: +This example reads public products from the test environment. ```java import com.whop.api.WhopApiClient; -import okhttp3.OkHttpClient; - -OkHttpClient customClient = ...; - -WhopApiClient client = WhopApiClient - .builder() - .httpClient(customClient) - .build(); -``` - -### Retries - -The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long -as the request is deemed retryable and the number of retry attempts has not grown larger than the configured -retry limit (default: 2). Before defaulting to exponential backoff, the SDK will first attempt to respect -the `Retry-After` header (as either in seconds or as an HTTP date), and then the `X-RateLimit-Reset` header -(as a Unix timestamp in epoch seconds); failing both of those, it will fall back to exponential backoff. - -Which status codes are retried depends on the `retry-status-codes` generator configuration: - -**`legacy`** (current default): retries on -- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) -- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) -- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (All server errors, including 500) - -**`recommended`**: retries on -- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) -- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) -- [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (Bad Gateway) -- [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (Service Unavailable) -- [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (Gateway Timeout) - -Use the `maxRetries` client option to configure this behavior. - -```java -import com.whop.api.WhopApiClient; - -WhopApiClient client = WhopApiClient - .builder() - .maxRetries(1) - .build(); -``` - -### Timeouts - -The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level. -```java -import com.whop.api.WhopApiClient; -import com.whop.api.core.RequestOptions; - -// Client level -WhopApiClient client = WhopApiClient - .builder() - .timeout(60) - .build(); - -// Request level -client.accessTokens().create( - ..., - RequestOptions - .builder() - .timeout(60) - .build() -); -``` - -### Custom Headers - -The SDK allows you to add custom headers to requests. You can configure headers at the client level or at the request level. - -```java -import com.whop.api.WhopApiClient; -import com.whop.api.core.RequestOptions; - -// Client level -WhopApiClient client = WhopApiClient - .builder() - .addHeader("X-Custom-Header", "custom-value") - .addHeader("X-Request-Id", "abc-123") - .build(); -; - -// Request level -client.accessTokens().create( - ..., - RequestOptions - .builder() - .addHeader("X-Request-Header", "request-value") - .build() -); -``` - -### Additional Body Properties - -If you need to send a request body property that is not yet part of the SDK (for example, a beta field), -use the `addBodyProperty` request option. Properties are sent with the key exactly as given and override -any property with the same key; for endpoints without a request body, they are sent as a JSON body. -This is supported for JSON and form-urlencoded request bodies, but not for multipart (file upload) requests. - -```java -import com.whop.api.core.RequestOptions; - -client.accessTokens().create( - ..., - RequestOptions - .builder() - .addBodyProperty("extra_field", "extra-value") - .build() -); -``` - -### Access Raw Response Data - -The SDK provides access to raw response data, including headers, through the `withRawResponse()` method. -The `withRawResponse()` method returns a raw client that wraps all responses with `body()` and `headers()` methods. -(A normal client's `response` is identical to a raw client's `response.body()`.) - -```java -WhopApiHttpResponse response = client.accessTokens().withRawResponse().create(...); +import com.whop.api.core.Environment; +import com.whop.api.resources.products.requests.ListProductsRequest; -System.out.println(response.body()); -System.out.println(response.headers().get("X-My-Header")); +public class ReadProducts { + public static void main(String[] args) { + try (WhopApiClient client = WhopApiClient.builder() + .environment(Environment.SANDBOX) + .build()) { + int count = client.products() + .list(ListProductsRequest.builder().first(1).build()) + .getItems().size(); + System.out.println(count); + } + } +} ``` -## 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! +On Android, run these calls on a background thread. +Pass your API key to `.token(...)` to create products. +Keep business API keys on your server. -On the other hand, contributions to the README are always very welcome! +[Android and Maven setup](INSTALL.md) · [API reference](reference.md)