Table of Contents

Interface IStravaClientBuilder

Namespace
Tudormobile.Strava.Client
Assembly
Tudormobile.Strava.Client.dll

Provides a builder interface for configuring and constructing StravaClient instances.

public interface IStravaClientBuilder : IBuilder<StravaClient>
Inherited Members

Remarks

This builder follows the fluent API pattern, allowing method chaining for easy configuration. Options can be set individually (WithClientId, WithAccessToken, etc.) or in bulk (WithOptions, UseAuthorization). Note that UseAuthorization() takes precedence over other option-setting methods.

Properties

AccessToken

Gets or sets the OAuth access token for API authentication.

string AccessToken { get; set; }

Property Value

string

The current access token. May expire and need to be refreshed.

Remarks

Setting this property triggers a rebuild of the Options object to maintain consistency. Access tokens typically expire after 6 hours and must be refreshed using the refresh token.

ClientId

Gets or sets the Strava application client identifier.

string ClientId { get; set; }

Property Value

string

The client ID assigned by Strava when you register your application.

Remarks

Setting this property triggers a rebuild of the Options object to maintain consistency. This is required for OAuth authentication flows.

ClientSecret

Gets or sets the Strava application client secret.

string ClientSecret { get; set; }

Property Value

string

The client secret assigned by Strava. Should be kept confidential.

Remarks

Setting this property triggers a rebuild of the Options object to maintain consistency. This is required for OAuth token refresh operations.

Options

Gets or sets the Strava options used for client configuration.

StravaOptions Options { get; set; }

Property Value

StravaOptions

Remarks

This property is the underlying storage for all OAuth credentials and configuration. Modifying this directly will affect all credential properties (ClientId, ClientSecret, etc.).

RefreshToken

Gets or sets the OAuth refresh token for obtaining new access tokens.

string RefreshToken { get; set; }

Property Value

string

The refresh token used to obtain new access tokens when they expire.

Remarks

Setting this property triggers a rebuild of the Options object to maintain consistency. Refresh tokens are long-lived and should be securely stored.

Methods

AddLogging(ILogger)

Adds the specified logger to the client builder for capturing diagnostic and operational messages.

IStravaClientBuilder AddLogging(ILogger logger)

Parameters

logger ILogger

The logger instance to use for logging client activity. Cannot be null.

Returns

IStravaClientBuilder

The current instance of the client builder for method chaining.

Remarks

Use this method to integrate with your application's logging infrastructure. The logger will capture information about API requests, responses, errors, and token refresh operations.

Example with Microsoft.Extensions.Logging: 

var logger = loggerFactory.CreateLogger<StravaClient>();
var client = builder
    .AddLogging(logger)
    .WithAccessToken("your-token")
    .Build();

SetOptions(string, string, string, string)

Internal helper method to atomically update all OAuth credentials at once.

void SetOptions(string clientId, string clientSecret, string accessToken, string refreshToken)

Parameters

clientId string

The Strava application client identifier.

clientSecret string

The Strava application client secret.

accessToken string

The current OAuth access token.

refreshToken string

The OAuth refresh token.

Remarks

This method ensures that all credentials are updated together, maintaining consistency in the Options object. This is called internally when any credential property is set.

UseAuthorization(StravaAuthorization)

Configures the client to use the specified Strava authorization settings for API requests.

IStravaClientBuilder UseAuthorization(StravaAuthorization authorization)

Parameters

authorization StravaAuthorization

The authorization information to use when authenticating requests. Cannot be null.

Returns

IStravaClientBuilder

The current IStravaClientBuilder instance for method chaining.

Remarks

This method provides the most direct way to configure authentication using an existing StravaAuthorization object, which contains all required OAuth credentials.

⚠️ Important: Using this method overrides any credentials previously set via WithOptions() or individual methods (WithClientId(), WithAccessToken(), etc.). This should be the last authentication configuration method called in the builder chain.

Prefer this method when you already have a StravaAuthorization object from a session or when migrating from the core StravaSession API.

WithAccessToken(string)

Configures the client to use the specified access token for authenticating requests to the Strava API.

IStravaClientBuilder WithAccessToken(string accessToken)

Parameters

accessToken string

The OAuth access token to use for API authentication. Cannot be null or empty.

Returns

IStravaClientBuilder

The current builder instance with the access token configured. This enables method chaining.

Remarks

Call this method before building the client to ensure all requests are authenticated. If the access token is invalid or expired, API requests may fail with an authentication error.

This is an alternative to setting UseAuthorization() or WithOptions(). You can chain this with other With* methods to configure all required credentials.

Access tokens typically expire after 6 hours. Ensure you also provide a refresh token if you want automatic token renewal.

WithClientId(string)

Sets the client identifier to be used for authenticating requests to the Strava API.

IStravaClientBuilder WithClientId(string clientId)

Parameters

clientId string

The client identifier assigned by Strava. Cannot be null or empty.

Returns

IStravaClientBuilder

The current builder instance with the specified client identifier applied.

Remarks

Call this method before building the client to ensure that all requests are authenticated with the correct client identifier. This method is typically used as part of a fluent configuration sequence.

This is an alternative to setting UseAuthorization() or WithOptions(). The client ID is required for OAuth flows and is obtained when you register your application with Strava.

Example: 

var client = builder
    .WithClientId("your-client-id")
    .WithClientSecret("your-secret")
    .WithAccessToken("your-token")
    .Build();

WithClientSecret(string)

Sets the client secret used for authenticating requests to the Strava API.

IStravaClientBuilder WithClientSecret(string clientSecret)

Parameters

clientSecret string

The client secret provided by Strava for your application. Cannot be null or empty.

Returns

IStravaClientBuilder

The current builder instance with the specified client secret configured.

Remarks

Call this method before building the client to ensure authentication is properly configured. The client secret is required for OAuth flows and should be kept confidential.

⚠️ Security: Never expose the client secret in client-side code or version control. Store it securely using environment variables, Azure Key Vault, or similar secure storage.

This is an alternative to setting UseAuthorization() or WithOptions().

WithHttpClient(HttpClient)

Configures the builder to use the specified HTTP client for sending requests to the Strava V3 API.

IStravaClientBuilder WithHttpClient(HttpClient httpClient)

Parameters

httpClient HttpClient

The HTTP client instance to use for all outgoing API requests. Cannot be null. The caller is responsible for managing the lifetime of the provided client.

Returns

IStravaClientBuilder

The current builder instance configured to use the specified HTTP client.

Remarks

Use this method to provide a custom-configured HttpClient, for example to set custom headers, proxies, or timeouts. If not set, a default HttpClient may be used by the implementation.

⚠️ Important: This method must be called; HttpClient is required for the client to function. The caller is responsible for managing the HttpClient lifetime (e.g., disposing it when done).

Consider using HttpClientFactory in production applications for proper HttpClient management.

WithOptions(StravaOptions)

Configures the builder with the specified Strava client options.

IStravaClientBuilder WithOptions(StravaOptions options)

Parameters

options StravaOptions

The options to use for configuring the Strava client. Cannot be null.

Returns

IStravaClientBuilder

The current builder instance configured with the specified options.

Remarks

This is an alternative to setting credentials individually using WithClientId(), WithAccessToken(), etc.

Use this method when you have a pre-configured StravaOptions object, such as from configuration or dependency injection.

Note: Using UseAuthorization() after this method will override these options.

WithRefreshToken(string)

Configures the client to use the specified refresh token for authentication with the Strava API.

IStravaClientBuilder WithRefreshToken(string refreshToken)

Parameters

refreshToken string

The refresh token to use for obtaining new access tokens. Cannot be null or empty.

Returns

IStravaClientBuilder

The current builder instance with the refresh token configured. This enables method chaining.

Remarks

Use this method when you have a refresh token and want the client to automatically handle access token renewal. The refresh token must be valid for the associated Strava application.

This is an alternative to setting UseAuthorization() or WithOptions().

Refresh tokens are long-lived and should be securely persisted. They allow the client to obtain new access tokens without requiring the user to re-authenticate.