client

Author: KSemenenko

AGENTS.md

@@ -81,10 +81,12 @@ If no new rule is detected → do not update the file.
 ### Documentation (ALL TASKS)
 
 - Docs live in `docs/` and `README.md`
+- Keep a GitHub Pages docs site in sync with `docs/`, using `DOCS-EXAMPLE/` as the reference template for structure and CI/pipeline
 - Update docs when behaviour changes
 - Update configuration examples when required
 - When adding new projects/providers, ensure `README.md` clearly documents installation, DI wiring, and basic usage examples
 - Where feasible, prefer provider options that can build vendor SDK clients from credentials (to reduce consumer boilerplate) while still allowing client injection for advanced scenarios
+- Avoid "ownership flags" like `ownsClient`; prefer a clear swap point (wrapper/factory) so lifetime and disposal rules stay simple and predictable
 - For providers that rely on vendor SDK clients (Graph/Drive/Dropbox/etc.), document how to obtain credentials/keys/tokens and include a minimal code snippet that builds the required SDK client instance
 
 ### Testing (ALL TASKS)

README.md

@@ -225,19 +225,30 @@ var tenantStorage = app.Services.GetRequiredKeyedService<IStorage>("tenant-a");
    var refreshToken = auth.RefreshToken; // store securely if you requested offline access
    ```
 
-5. Create the Dropbox client and register Dropbox storage with a root path (use `/` for full access apps or `/Apps/<your-app>` for app folders):
+5. Register Dropbox storage with a root path (use `/` for full access apps or `/Apps/<your-app>` for app folders). You can let the provider create the SDK client from credentials:
 
    ```csharp
-   using Dropbox.Api;
    builder.Services.AddDropboxStorageAsDefault(options =>
    {
        var accessToken = configuration["Dropbox:AccessToken"]!;
-       options.DropboxClient = new DropboxClient(accessToken);
+       options.AccessToken = accessToken;
        options.RootPath = "/apps/my-app";
        options.CreateContainerIfNotExists = true;
    });
    ```
 
+   Or, for production, prefer refresh tokens (offline access):
+
+   ```csharp
+   builder.Services.AddDropboxStorageAsDefault(options =>
+   {
+       options.RefreshToken = configuration["Dropbox:RefreshToken"]!;
+       options.AppKey = configuration["Dropbox:AppKey"]!;
+       options.AppSecret = configuration["Dropbox:AppSecret"]; // optional when using PKCE
+       options.RootPath = "/apps/my-app";
+   });
+   ```
+
 6. Store tokens in user secrets or environment variables; never commit them to source control.
 
 **CloudKit (iCloud app data)**

Storages/ManagedCode.Storage.Dropbox/Clients/DropboxClientWrapper.cs

@@ -10,7 +10,7 @@
 
 namespace ManagedCode.Storage.Dropbox.Clients;
 
-public class DropboxClientWrapper : IDropboxClientWrapper
+public class DropboxClientWrapper : IDropboxClientWrapper, IDisposable
 {
     private readonly DropboxClient _client;
 
@@ -19,6 +19,11 @@ public DropboxClientWrapper(DropboxClient client)
         _client = client ?? throw new ArgumentNullException(nameof(client));
     }
 
+    public void Dispose()
+    {
+        _client.Dispose();
+    }
+
     public async Task EnsureRootAsync(string rootPath, bool createIfNotExists, CancellationToken cancellationToken)
     {
         if (string.IsNullOrWhiteSpace(rootPath))

Storages/ManagedCode.Storage.Dropbox/DropboxStorage.cs

@@ -36,9 +36,47 @@ protected override IDropboxClientWrapper CreateStorageClient()
             return new DropboxClientWrapper(StorageOptions.DropboxClient);
         }
 
+        if (!string.IsNullOrWhiteSpace(StorageOptions.AccessToken))
+        {
+            var client = StorageOptions.DropboxClientConfig == null
+                ? new global::Dropbox.Api.DropboxClient(StorageOptions.AccessToken)
+                : new global::Dropbox.Api.DropboxClient(StorageOptions.AccessToken, StorageOptions.DropboxClientConfig);
+
+            return new DropboxClientWrapper(client);
+        }
+
+        if (!string.IsNullOrWhiteSpace(StorageOptions.RefreshToken))
+        {
+            if (string.IsNullOrWhiteSpace(StorageOptions.AppKey))
+            {
+                throw new InvalidOperationException("Dropbox AppKey is required when configuring the storage with a refresh token.");
+            }
+
+            var client = CreateDropboxClientFromRefreshToken(StorageOptions.RefreshToken, StorageOptions.AppKey, StorageOptions.AppSecret, StorageOptions.DropboxClientConfig);
+            return new DropboxClientWrapper(client);
+        }
+
         throw new InvalidOperationException("Dropbox client is not configured for storage.");
     }
 
+    private static global::Dropbox.Api.DropboxClient CreateDropboxClientFromRefreshToken(
+        string refreshToken,
+        string appKey,
+        string? appSecret,
+        global::Dropbox.Api.DropboxClientConfig? config)
+    {
+        if (!string.IsNullOrWhiteSpace(appSecret))
+        {
+            return config == null
+                ? new global::Dropbox.Api.DropboxClient(refreshToken, appKey, appSecret)
+                : new global::Dropbox.Api.DropboxClient(refreshToken, appKey, appSecret, config);
+        }
+
+        return config == null
+            ? new global::Dropbox.Api.DropboxClient(refreshToken, appKey)
+            : new global::Dropbox.Api.DropboxClient(refreshToken, appKey, config);
+    }
+
     protected override async Task<Result> CreateContainerInternalAsync(CancellationToken cancellationToken = default)
     {
         try

Storages/ManagedCode.Storage.Dropbox/DropboxStorageProvider.cs

@@ -32,6 +32,11 @@ public IStorageOptions GetDefaultOptions()
             RootPath = defaultOptions.RootPath,
             DropboxClient = defaultOptions.DropboxClient,
             Client = defaultOptions.Client,
+            AccessToken = defaultOptions.AccessToken,
+            RefreshToken = defaultOptions.RefreshToken,
+            AppKey = defaultOptions.AppKey,
+            AppSecret = defaultOptions.AppSecret,
+            DropboxClientConfig = defaultOptions.DropboxClientConfig,
             CreateContainerIfNotExists = defaultOptions.CreateContainerIfNotExists
         };
     }

Storages/ManagedCode.Storage.Dropbox/Extensions/ServiceCollectionExtensions.cs

@@ -85,9 +85,17 @@ public static IServiceCollection AddDropboxStorageAsDefault(this IServiceCollect
 
     private static void CheckConfiguration(DropboxStorageOptions options)
     {
-        if (options.Client == null && options.DropboxClient == null)
+        if (!string.IsNullOrWhiteSpace(options.RefreshToken) && string.IsNullOrWhiteSpace(options.AppKey))
         {
-            throw new BadConfigurationException("Dropbox storage requires either a configured DropboxClient or a custom IDropboxClientWrapper.");
+            throw new BadConfigurationException("Dropbox storage configuration with a refresh token requires AppKey (and optionally AppSecret).");
+        }
+
+        if (options.Client == null
+            && options.DropboxClient == null
+            && string.IsNullOrWhiteSpace(options.AccessToken)
+            && string.IsNullOrWhiteSpace(options.RefreshToken))
+        {
+            throw new BadConfigurationException("Dropbox storage requires either a configured DropboxClient, a custom IDropboxClientWrapper, or credentials (AccessToken / RefreshToken + AppKey).");
         }
     }
 }

Storages/ManagedCode.Storage.Dropbox/Options/DropboxStorageOptions.cs

@@ -10,6 +10,28 @@ public class DropboxStorageOptions : IStorageOptions
 
     public DropboxClient? DropboxClient { get; set; }
 
+    /// <summary>
+    /// OAuth2 access token (short-lived or long-lived) used to create a <see cref="global::Dropbox.Api.DropboxClient"/> when <see cref="DropboxClient"/> is not provided.
+    /// </summary>
+    public string? AccessToken { get; set; }
+
+    /// <summary>
+    /// OAuth2 refresh token used to create a <see cref="global::Dropbox.Api.DropboxClient"/> when <see cref="DropboxClient"/> is not provided.
+    /// </summary>
+    public string? RefreshToken { get; set; }
+
+    /// <summary>
+    /// Dropbox app key (required when using <see cref="RefreshToken"/>).
+    /// </summary>
+    public string? AppKey { get; set; }
+
+    /// <summary>
+    /// Dropbox app secret (optional when using PKCE refresh tokens).
+    /// </summary>
+    public string? AppSecret { get; set; }
+
+    public DropboxClientConfig? DropboxClientConfig { get; set; }
+
     public string RootPath { get; set; } = string.Empty;
 
     public bool CreateContainerIfNotExists { get; set; } = true;

Tests/ManagedCode.Storage.Tests/Storages/Abstracts/UploadTests.cs

@@ -25,11 +25,12 @@ public async Task UploadAsync_AsText_WithoutOptions()
 
         // Act
         var result = await Storage.UploadAsync(uploadContent);
-        var downloadedResult = await Storage.DownloadAsync(result.Value!.Name);
 
         // Assert
         result.IsSuccess
             .ShouldBeTrue();
+
+        var downloadedResult = await Storage.DownloadAsync(result.Value!.Name);
         downloadedResult.IsSuccess
             .ShouldBeTrue();
     }
@@ -44,11 +45,12 @@ public async Task UploadAsync_AsStream_WithoutOptions()
 
         // Act
         var result = await Storage.UploadAsync(stream);
-        var downloadedResult = await Storage.DownloadAsync(result.Value!.Name);
 
         // Assert
         result.IsSuccess
             .ShouldBeTrue();
+
+        var downloadedResult = await Storage.DownloadAsync(result.Value!.Name);
         downloadedResult.IsSuccess
             .ShouldBeTrue();
     }

Tests/ManagedCode.Storage.Tests/Storages/CloudDrive/CloudDriveDependencyInjectionTests.cs

@@ -68,6 +68,47 @@ public void Dropbox_WhenClientNotConfigured_ShouldThrow()
             services.AddDropboxStorage(options => options.RootPath = "/apps/demo"));
     }
 
+    [Fact]
+    public void Dropbox_WhenAccessTokenConfigured_ShouldResolve()
+    {
+        var services = new ServiceCollection();
+        services.AddDropboxStorage(options =>
+        {
+            options.RootPath = "/apps/demo";
+            options.AccessToken = "test-token";
+        });
+
+        using var provider = services.BuildServiceProvider();
+        provider.GetRequiredService<IDropboxStorage>().ShouldNotBeNull();
+    }
+
+    [Fact]
+    public void Dropbox_WhenRefreshTokenMissingAppKey_ShouldThrow()
+    {
+        var services = new ServiceCollection();
+        Should.Throw<BadConfigurationException>(() =>
+            services.AddDropboxStorage(options =>
+            {
+                options.RootPath = "/apps/demo";
+                options.RefreshToken = "refresh-token";
+            }));
+    }
+
+    [Fact]
+    public void Dropbox_WhenRefreshTokenConfigured_ShouldResolve()
+    {
+        var services = new ServiceCollection();
+        services.AddDropboxStorage(options =>
+        {
+            options.RootPath = "/apps/demo";
+            options.RefreshToken = "refresh-token";
+            options.AppKey = "app-key";
+        });
+
+        using var provider = services.BuildServiceProvider();
+        provider.GetRequiredService<IDropboxStorage>().ShouldNotBeNull();
+    }
+
     [Fact]
     public void GoogleDrive_AddAsDefault_ShouldResolveIStorage()
     {

Tests/ManagedCode.Storage.Tests/Storages/CloudDrive/DropboxClientWrapperHttpTests.cs

@@ -9,7 +9,9 @@
 using System.Threading;
 using System.Threading.Tasks;
 using Dropbox.Api;
+using ManagedCode.Storage.Dropbox;
 using ManagedCode.Storage.Dropbox.Clients;
+using ManagedCode.Storage.Dropbox.Options;
 using Shouldly;
 using Xunit;
 
@@ -24,7 +26,8 @@ public async Task DropboxClientWrapper_WithHttpHandler_RoundTrip()
         var httpClient = new HttpClient(handler);
         var config = new DropboxClientConfig("ManagedCode.Storage.Tests")
         {
-            HttpClient = httpClient
+            HttpClient = httpClient,
+            LongPollHttpClient = httpClient
         };
 
         using var dropboxClient = new DropboxClient("test-token", config);
@@ -59,6 +62,39 @@ public async Task DropboxClientWrapper_WithHttpHandler_RoundTrip()
         (await wrapper.DeleteAsync("/apps/demo", "file.json", CancellationToken.None)).ShouldBeFalse();
     }
 
+    [Fact]
+    public async Task DropboxStorage_WithAccessTokenAndHttpHandler_RoundTrip()
+    {
+        var handler = new FakeDropboxHttpHandler();
+        var httpClient = new HttpClient(handler);
+        var config = new DropboxClientConfig("ManagedCode.Storage.Tests")
+        {
+            HttpClient = httpClient,
+            LongPollHttpClient = httpClient
+        };
+
+        using var storage = new DropboxStorage(new DropboxStorageOptions
+        {
+            RootPath = "/apps/demo",
+            AccessToken = "test-token",
+            DropboxClientConfig = config,
+            CreateContainerIfNotExists = true
+        });
+
+        (await storage.UploadAsync("dropbox payload", options => options.FileName = "file.json")).IsSuccess.ShouldBeTrue();
+
+        var exists = await storage.ExistsAsync("file.json");
+        exists.IsSuccess.ShouldBeTrue();
+        exists.Value.ShouldBeTrue();
+
+        var download = await storage.DownloadAsync("file.json");
+        download.IsSuccess.ShouldBeTrue();
+        using (var reader = new StreamReader(download.Value.FileStream, Encoding.UTF8))
+        {
+            (await reader.ReadToEndAsync()).ShouldBe("dropbox payload");
+        }
+    }
+
     private sealed class FakeDropboxHttpHandler : HttpMessageHandler
     {
         private const string ApiHost = "api.dropboxapi.com";