AsyncCloudPDFClientBuilder.java

/**
 * This file was auto-generated by Fern from our API Definition.
 */
package com.cloudpdf.api;

import com.cloudpdf.api.core.ClientOptions;
import com.cloudpdf.api.core.Environment;
import com.cloudpdf.api.core.LogConfig;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;
import okhttp3.OkHttpClient;

public class AsyncCloudPDFClientBuilder {
    private Optional<Integer> timeout = Optional.empty();

    private Optional<Integer> maxRetries = Optional.empty();

    private Optional<Long> initialRetryDelayMillis = Optional.empty();

    private Optional<Long> maxRetryDelayMillis = Optional.empty();

    private Optional<Double> retryJitterFactor = Optional.empty();

    private final Map<String, String> customHeaders = new HashMap<>();

    private String token = null;

    private Environment environment;

    private OkHttpClient httpClient;

    private Optional<LogConfig> logging = Optional.empty();

    /**
     * Sets token
     */
    public AsyncCloudPDFClientBuilder token(String token) {
        this.token = token;
        return this;
    }

    public AsyncCloudPDFClientBuilder url(String url) {
        this.environment = Environment.custom(url);
        return this;
    }

    /**
     * Sets the timeout (in seconds) for the client. Defaults to 60 seconds.
     */
    public AsyncCloudPDFClientBuilder timeout(int timeout) {
        this.timeout = Optional.of(timeout);
        return this;
    }

    /**
     * Sets the maximum number of retries for the client. Defaults to 2 retries.
     */
    public AsyncCloudPDFClientBuilder maxRetries(int maxRetries) {
        this.maxRetries = Optional.of(maxRetries);
        return this;
    }

    /**
     * Sets the initial delay (in milliseconds) used for exponential backoff between retries. Defaults to 1000 milliseconds.
     */
    public AsyncCloudPDFClientBuilder initialRetryDelayMillis(long initialRetryDelayMillis) {
        this.initialRetryDelayMillis = Optional.of(initialRetryDelayMillis);
        return this;
    }

    /**
     * Sets the maximum delay (in milliseconds) between retries. Defaults to 60000 milliseconds.
     */
    public AsyncCloudPDFClientBuilder maxRetryDelayMillis(long maxRetryDelayMillis) {
        this.maxRetryDelayMillis = Optional.of(maxRetryDelayMillis);
        return this;
    }

    /**
     * Sets the jitter factor (between 0 and 1) applied to retry delays. Defaults to 0.2.
     */
    public AsyncCloudPDFClientBuilder retryJitterFactor(double retryJitterFactor) {
        this.retryJitterFactor = Optional.of(retryJitterFactor);
        return this;
    }

    /**
     * Sets the underlying OkHttp client
     */
    public AsyncCloudPDFClientBuilder httpClient(OkHttpClient httpClient) {
        this.httpClient = httpClient;
        return this;
    }

    /**
     * Configure logging for the SDK. Silent by default — no log output unless explicitly configured.
     */
    public AsyncCloudPDFClientBuilder logging(LogConfig logging) {
        this.logging = Optional.of(logging);
        return this;
    }

    /**
     * Add a custom header to be sent with all requests.
     * For headers that need to be computed dynamically or conditionally, use the setAdditional() method override instead.
     *
     * @param name The header name
     * @param value The header value
     * @return This builder for method chaining
     */
    public AsyncCloudPDFClientBuilder addHeader(String name, String value) {
        this.customHeaders.put(name, value);
        return this;
    }

    protected ClientOptions buildClientOptions() {
        ClientOptions.Builder builder = ClientOptions.builder();
        setEnvironment(builder);
        setAuthentication(builder);
        setHttpClient(builder);
        setTimeouts(builder);
        setRetries(builder);
        setLogging(builder);
        for (Map.Entry<String, String> header : this.customHeaders.entrySet()) {
            builder.addHeader(header.getKey(), header.getValue());
        }
        setAdditional(builder);
        return builder.build();
    }

    /**
     * Sets the environment configuration for the client.
     * Override this method to modify URLs or add environment-specific logic.
     *
     * @param builder The ClientOptions.Builder to configure
     */
    protected void setEnvironment(ClientOptions.Builder builder) {
        builder.environment(this.environment);
    }

    /**
     * Override this method to customize authentication.
     * This method is called during client options construction to set up authentication headers.
     *
     * @param builder The ClientOptions.Builder to configure
     *
     * Example:
     * <pre>{@code
     * &#64;Override
     * protected void setAuthentication(ClientOptions.Builder builder) {
     *     super.setAuthentication(builder); // Keep existing auth
     *     builder.addHeader("X-API-Key", this.apiKey);
     * }
     * }</pre>
     */
    protected void setAuthentication(ClientOptions.Builder builder) {
        if (this.token != null) {
            builder.addHeader("Authorization", "Bearer " + this.token);
        }
    }

    /**
     * Sets the request timeout configuration.
     * Override this method to customize timeout behavior.
     *
     * @param builder The ClientOptions.Builder to configure
     */
    protected void setTimeouts(ClientOptions.Builder builder) {
        if (this.timeout.isPresent()) {
            builder.timeout(this.timeout.get());
        }
    }

    /**
     * Sets the retry configuration for failed requests.
     * Override this method to implement custom retry strategies.
     *
     * @param builder The ClientOptions.Builder to configure
     */
    protected void setRetries(ClientOptions.Builder builder) {
        if (this.maxRetries.isPresent()) {
            builder.maxRetries(this.maxRetries.get());
        }
        if (this.initialRetryDelayMillis.isPresent()) {
            builder.initialRetryDelayMillis(this.initialRetryDelayMillis.get());
        }
        if (this.maxRetryDelayMillis.isPresent()) {
            builder.maxRetryDelayMillis(this.maxRetryDelayMillis.get());
        }
        if (this.retryJitterFactor.isPresent()) {
            builder.retryJitterFactor(this.retryJitterFactor.get());
        }
    }

    /**
     * Sets the OkHttp client configuration.
     * Override this method to customize HTTP client behavior (interceptors, connection pools, etc).
     *
     * @param builder The ClientOptions.Builder to configure
     */
    protected void setHttpClient(ClientOptions.Builder builder) {
        if (this.httpClient != null) {
            builder.httpClient(this.httpClient);
        }
    }

    /**
     * Sets the logging configuration for the SDK.
     * Override this method to customize logging behavior.
     *
     * @param builder The ClientOptions.Builder to configure
     */
    protected void setLogging(ClientOptions.Builder builder) {
        if (this.logging.isPresent()) {
            builder.logging(this.logging.get());
        }
    }

    /**
     * Override this method to add any additional configuration to the client.
     * This method is called at the end of the configuration chain, allowing you to add
     * custom headers, modify settings, or perform any other client customization.
     *
     * @param builder The ClientOptions.Builder to configure
     *
     * Example:
     * <pre>{@code
     * &#64;Override
     * protected void setAdditional(ClientOptions.Builder builder) {
     *     builder.addHeader("X-Request-ID", () -&gt; UUID.randomUUID().toString());
     *     builder.addHeader("X-Client-Version", "1.0.0");
     * }
     * }</pre>
     */
    protected void setAdditional(ClientOptions.Builder builder) {}

    /**
     * Override this method to add custom validation logic before the client is built.
     * This method is called at the beginning of the build() method to ensure the configuration is valid.
     * Throw an exception to prevent client creation if validation fails.
     *
     * Example:
     * <pre>{@code
     * &#64;Override
     * protected void validateConfiguration() {
     *     super.validateConfiguration(); // Run parent validations
     *     if (tenantId == null || tenantId.isEmpty()) {
     *         throw new IllegalStateException("tenantId is required");
     *     }
     * }
     * }</pre>
     */
    protected void validateConfiguration() {}

    public AsyncCloudPDFClient build() {
        if (token == null) {
            throw new RuntimeException("Please provide token");
        }
        validateConfiguration();
        return new AsyncCloudPDFClient(buildClientOptions());
    }
}