Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .fernignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
262 changes: 37 additions & 225 deletions README.md
Original file line number Diff line number Diff line change
@@ -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("<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)
Loading