chore: sync .NET client with Apify OpenAPI spec v2-2026-07-08T143931Z

- Bump ApiSpecVersion to v2-2026-07-08T143931Z and client version to 0.1.2
- Align User-Agent OS token with reference clients (win32/darwin/linux/android/freebsd)
- Add brotli request-body compression for bodies >= 1024 bytes (Content-Encoding: br)
- Document the Actor versions / environment-variables sub-API and make doc token
  preamble null-safe

Author: claude

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.2
+
+- Bumped `ApifyClientVersion.ApiSpecVersion` to the Apify OpenAPI spec `v2-2026-07-08T143931Z` and the
+  project version to `0.1.2`.
+- Aligned the `User-Agent` OS token with the other Apify clients: it now uses the short, lowercase
+  platform identifier (`win32`, `darwin`, `linux`, `android`, `freebsd`) instead of `windows`.
+- Request bodies of at least 1024 bytes are now compressed with brotli (`Content-Encoding: br`) before
+  sending. Brotli is always used because .NET's `BrotliStream` is always available, so the reference
+  client's gzip fallback (for runtimes lacking brotli) is not needed.
+
 ## 0.1.1
 
 - Bumped `ApifyClientVersion.ApiSpecVersion` to the Apify OpenAPI spec `v2-2026-07-07T132551Z` and the

docs/README.md

@@ -57,7 +57,8 @@ Console.WriteLine("Item count: " + items.Count);
 
 `new ApifyClient("my-api-token")` takes the token as an explicit argument — it does **not** read
 `APIFY_TOKEN` (or any other environment variable) automatically. Read it yourself if you want that,
-e.g. `new ApifyClient(Environment.GetEnvironmentVariable("APIFY_TOKEN"))`.
+e.g. `new ApifyClient(Environment.GetEnvironmentVariable("APIFY_TOKEN") ?? throw new InvalidOperationException("Set APIFY_TOKEN"))`
+(the null-coalescing throw keeps the call null-safe when the variable is unset).
 
 Get your API token from the
 [Apify Console → Settings → API & Integrations](https://console.apify.com/settings/integrations).
@@ -70,7 +71,7 @@ the `using` directives for whichever ones a file references:
 | Namespace | What lives here |
 |---|---|
 | `Apify.Client` | The entry point (`ApifyClient`), `ApifyClientOptions`, `ApifyClientVersion`, and the log-redirection helper `StreamedLog`. |
-| `Apify.Client.Resources` | Every resource client the entry point returns — `ActorClient`, `RunClient`, `BuildClient`, `DatasetClient`, `KeyValueStoreClient`, `RequestQueueClient`, `TaskClient`, `ScheduleClient`, `LogClient`, `UserClient`, the `…CollectionClient` types (including `NestedWebhookCollectionClient` and `WebhookDispatchCollectionClient`), etc. |
+| `Apify.Client.Resources` | Every resource client the entry point returns — `ActorClient`, `RunClient`, `BuildClient`, `DatasetClient`, `KeyValueStoreClient`, `RequestQueueClient`, `TaskClient`, `ScheduleClient`, `LogClient`, `UserClient`, `ActorVersionClient`, `ActorEnvVarClient`, the `…CollectionClient` types (including `ActorVersionCollectionClient`, `ActorEnvVarCollectionClient`, `NestedWebhookCollectionClient`, and `WebhookDispatchCollectionClient`), etc. |
 | `Apify.Client.Models` | Data models returned by the clients — `Actor`, `ActorRun`, `Build`, `Dataset`, `RequestQueueRequest`, `ActorEnvVar`, `PaginationList<T>`, and so on. |
 | `Apify.Client.Options` | The option/request objects passed into methods — `ActorStartOptions`, `DatasetListItemsOptions`, `DownloadItemsFormat`, `ListOptions`, `SetRecordOptions`, `StorageListOptions`, etc. |
 | `Apify.Client.Exceptions` | `ApifyApiException` and `ApifyTransportException`. |

docs/actors.md

@@ -48,7 +48,7 @@ foreach (var actor in page.Items)
 - `DefaultBuildAsync(int? waitForFinish = null)` → `BuildClient`.
 - `LastRun(LastRunOptions? options = null)` → `RunClient` (filter by `Status`/`Origin`).
 - `Builds()` → `BuildCollectionClient`; `Runs()` → `RunCollectionClient`.
-- `Version(string versionNumber)` / `Versions()` — Actor versions.
+- `Version(string versionNumber)` → `ActorVersionClient`; `Versions()` → `ActorVersionCollectionClient` — a single Actor version and the version collection.
 - `Webhooks()` → read-only `NestedWebhookCollectionClient`.
 
 `ActorStartOptions` fields:
@@ -87,6 +87,51 @@ against) and `ContentType` (`string?`, content type of the input; defaults to `a
 
 ## Versions and environment variables
 
+Manage an Actor's versions with `client.Actor(id).Versions()` (the whole collection) and
+`client.Actor(id).Version(versionNumber)` (one version). Each version in turn owns a collection of
+environment variables, reached with `.EnvVars()` / `.EnvVar(name)`.
+
+### Version collection — `client.Actor(id).Versions()` → `ActorVersionCollectionClient`
+
+- `ListAsync(ListOptions? options = null)` — list the Actor's versions (one page). Returns
+  `PaginationList<ActorVersion>`.
+- `IterateAsync(ListOptions? options = null)` → `IAsyncEnumerable<ActorVersion>` — lazily iterate every
+  version across pages, fetching each page on demand.
+- `CreateAsync(object version)` — create a version from any JSON-serializable definition. Returns
+  `ActorVersion`.
+
+`ListOptions` fields: `Offset` (`int?`, items to skip), `Limit` (`int?`, page size), `Desc` (`bool?`,
+newest-first when `true`).
+
+### Single version — `client.Actor(id).Version(versionNumber)` → `ActorVersionClient`
+
+`versionNumber` is the version identifier (e.g. `0.1`).
+
+- `GetAsync()` → `ActorVersion?` (null if not found).
+- `UpdateAsync(object newFields)` → `ActorVersion` — update with any JSON-serializable set of fields.
+- `DeleteAsync()`.
+- `EnvVars()` → `ActorEnvVarCollectionClient` — this version's environment-variable collection.
+- `EnvVar(string name)` → `ActorEnvVarClient` — a single environment variable of this version.
+
+### Env-var collection — `Version(versionNumber).EnvVars()` → `ActorEnvVarCollectionClient`
+
+- `ListAsync()` — list the version's environment variables (the endpoint returns them in a single page).
+  Returns `PaginationList<ActorEnvVar>`.
+- `IterateAsync()` → `IAsyncEnumerable<ActorEnvVar>` — iterate the variables; provided for parity with
+  the other collection iterators (yields the single page's items).
+- `CreateAsync(ActorEnvVar envVar)` → `ActorEnvVar` — create an environment variable.
+
+### Single env-var — `Version(versionNumber).EnvVar(name)` → `ActorEnvVarClient`
+
+`name` is the environment variable's name.
+
+- `GetAsync()` → `ActorEnvVar?` (null if not found).
+- `UpdateAsync(ActorEnvVar envVar)` → `ActorEnvVar`.
+- `DeleteAsync()`.
+
+See [`ActorVersion`](models.md#actorversion) and [`ActorEnvVar`](models.md#actorenvvar) for the returned
+models and the `ActorEnvVar` constructor used below.
+
 ```csharp
 using Apify.Client;
 using Apify.Client.Models;

docs/examples.md

@@ -1,9 +1,11 @@
 # Examples
 
-Each example below is a complete, runnable scenario. The canonical, compiled versions live in
-[`tests/Apify.Client.Tests/Examples`](../tests/Apify.Client.Tests/Examples) and are executed
-end-to-end against the live API by the **Test examples** CI step (they require an `APIFY_TOKEN`), so
-the snippets here are guaranteed to stay valid and working.
+Each example below is a complete, runnable scenario. The canonical, compiled versions live in the
+client's source repository under
+[`tests/Apify.Client.Tests/Examples`](../tests/Apify.Client.Tests/Examples) — a repo-internal path that
+is not part of the published NuGet package — and are executed end-to-end against the live API by the
+**Test examples** CI step (they require an `APIFY_TOKEN`), so the snippets here are guaranteed to stay
+valid and working.
 
 Every snippet runs inside an `async` context and assumes the following `using` directives appear at the
 top of the file, **before** any top-level statements (a `using` after the first statement is a `CS1529`
@@ -16,7 +18,9 @@ using Apify.Client;
 using Apify.Client.Models;
 using Apify.Client.Options;
 
-var client = new ApifyClient(Environment.GetEnvironmentVariable("APIFY_TOKEN"));
+var client = new ApifyClient(
+    Environment.GetEnvironmentVariable("APIFY_TOKEN")
+    ?? throw new InvalidOperationException("Set the APIFY_TOKEN environment variable."));
 ```
 
 ## Run a store Actor and read its dataset

docs/misc.md

@@ -54,6 +54,10 @@ var client = new ApifyClient("my-api-token");
 var me = await client.Me().GetAsync();
 Console.WriteLine(me?.Username);
 var usage = await client.Me().MonthlyUsageAsync();
+
+// Any user's public profile by id (no private fields, and no account-only methods).
+var otherUser = await client.User("some-user-id").GetAsync();
+Console.WriteLine(otherUser?.Username);
 ```
 
 ## Logs — `client.Log(buildOrRunId)`
@@ -66,10 +70,16 @@ var usage = await client.Me().MonthlyUsageAsync();
 
 ```csharp
 using System;
+using System.IO;
 using Apify.Client;
 using Apify.Client.Options;
 
 var client = new ApifyClient("my-api-token");
 var log = await client.Log("some-run-id").GetAsync(new LogOptions { Raw = true });
 Console.WriteLine(log);
+
+// Read a run's raw live log as a stream (the low-level alternative to GetStreamedLog's sink redirection).
+await using var logStream = await client.Run("some-run-id").GetStreamedLogAsync();
+using var reader = new StreamReader(logStream);
+Console.WriteLine(await reader.ReadToEndAsync());
 ```

src/Apify.Client/ApifyClient.cs

@@ -266,24 +266,40 @@ private static string BuildUserAgent(string? suffix, Func<bool> isAtHomeFn)
         return ua;
     }
 
-    /// <summary>The lowercase operating-system family name, matching the reference clients' convention.</summary>
+    /// <summary>
+    /// The short, lowercase platform identifier used in the <c>User-Agent</c> OS token. These match the
+    /// reference client's Node <c>os.platform()</c> values (<c>win32</c>, <c>darwin</c>, <c>linux</c>,
+    /// <c>android</c>, <c>freebsd</c>) rather than uname-style names, keeping the token aligned across
+    /// Apify clients. Android is checked before Linux so an Android runtime is reported as
+    /// <c>android</c> rather than <c>linux</c>.
+    /// </summary>
     private static string CurrentOs()
     {
         if (OperatingSystem.IsWindows())
         {
-            return "windows";
+            return "win32";
         }
 
         if (OperatingSystem.IsMacOS())
         {
             return "darwin";
         }
 
+        if (OperatingSystem.IsAndroid())
+        {
+            return "android";
+        }
+
         if (OperatingSystem.IsLinux())
         {
             return "linux";
         }
 
+        if (OperatingSystem.IsFreeBSD())
+        {
+            return "freebsd";
+        }
+
         return "unknown";
     }
 }

src/Apify.Client/ApifyClientVersion.cs

@@ -14,11 +14,11 @@ public static class ApifyClientVersion
     /// The semantic version of this client library (see https://semver.org/). Changes to the public
     /// interface other than additive ones are considered breaking changes.
     /// </summary>
-    public const string ClientVersion = "0.1.1";
+    public const string ClientVersion = "0.1.2";
 
     /// <summary>
     /// The version of the Apify OpenAPI specification this client was generated and verified against.
     /// Corresponds to the <c>info.version</c> field of the Apify OpenAPI document.
     /// </summary>
-    public const string ApiSpecVersion = "v2-2026-07-07T132551Z";
+    public const string ApiSpecVersion = "v2-2026-07-08T143931Z";
 }

src/Apify.Client/Internal/HttpClientCore.cs

@@ -1,6 +1,8 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
+using System.IO;
+using System.IO.Compression;
 using System.Net.Http;
 using System.Net.Http.Headers;
 using System.Text;
@@ -31,6 +33,15 @@ internal sealed class HttpClientCore
 
     private const int NotFound = 404;
 
+    /// <summary>
+    /// Request bodies whose size in bytes is at or above this threshold are compressed before sending,
+    /// matching the reference client's minimum-compression size.
+    /// </summary>
+    private const int MinCompressBytes = 1024;
+
+    /// <summary>The <c>Content-Encoding</c> token used for brotli-compressed request bodies.</summary>
+    private const string BrotliEncoding = "br";
+
     private readonly IHttpTransport _transport;
     private readonly string? _token;
     private readonly RetryConfig _retry;
@@ -68,6 +79,9 @@ public async Task<HttpResponseMessage> CallAsync(
         var maxAttempts = _retry.MaxRetries + 1;
         var path = ExtractPath(url);
         var baseTimeout = timeout ?? TimeSpan.FromSeconds(_retry.TimeoutSecs);
+        // Normalize (and, when large enough, compress) the body once up front so retries reuse the same
+        // prepared payload instead of re-encoding and re-compressing on every attempt.
+        var prepared = PrepareBody(body, bodyBytes, contentType);
         Exception? lastError = null;
 
         for (var attempt = 1; attempt <= maxAttempts; attempt++)
@@ -76,7 +90,7 @@ public async Task<HttpResponseMessage> CallAsync(
             try
             {
                 var response = await SendOnceAsync(
-                    method, url, body, bodyBytes, contentType, extraHeaders,
+                    method, url, prepared, extraHeaders,
                     AttemptTimeout(baseTimeout, attempt), cancellationToken).ConfigureAwait(false);
 
                 var status = (int)response.StatusCode;
@@ -114,31 +128,27 @@ await Task.Delay(TimeSpan.FromMilliseconds(RandomizedDelayMillis(delayMillis)),
     /// <summary>Opens a live streaming response (single attempt, no retry). Used by log streaming.</summary>
     public Task<HttpResponseMessage> StreamAsync(string url, CancellationToken cancellationToken)
     {
-        var request = BuildRequest(HttpMethod.Get, url, null, null, string.Empty, null);
+        var request = BuildRequest(HttpMethod.Get, url, default, null);
         return _transport.SendAsync(request, TimeSpan.FromSeconds(_retry.TimeoutSecs), streaming: true, cancellationToken);
     }
 
     private async Task<HttpResponseMessage> SendOnceAsync(
         HttpMethod method,
         string url,
-        string? body,
-        byte[]? bodyBytes,
-        string contentType,
+        PreparedBody prepared,
         IReadOnlyDictionary<string, string>? extraHeaders,
         TimeSpan timeout,
         CancellationToken cancellationToken)
     {
-        using var request = BuildRequest(method, url, body, bodyBytes, contentType, extraHeaders);
+        using var request = BuildRequest(method, url, prepared, extraHeaders);
         return await _transport.SendAsync(request, timeout, streaming: false, cancellationToken).ConfigureAwait(false);
     }
 
     /// <summary>Builds a fully-prepared request with auth, User-Agent, content type and extra headers.</summary>
     private HttpRequestMessage BuildRequest(
         HttpMethod method,
         string url,
-        string? body,
-        byte[]? bodyBytes,
-        string contentType,
+        PreparedBody prepared,
         IReadOnlyDictionary<string, string>? extraHeaders)
     {
         var request = new HttpRequestMessage(method, url);
@@ -156,22 +166,67 @@ private HttpRequestMessage BuildRequest(
             }
         }
 
-        // Raw bytes take precedence so binary records (e.g. images, gzip) are sent verbatim; a string body
-        // is UTF-8 encoded. Setting the content type verbatim (no charset appended unless the caller added one).
-        HttpContent? content = bodyBytes is not null
-            ? new ByteArrayContent(bodyBytes)
-            : body is not null ? new StringContent(body, Encoding.UTF8) : null;
-        if (content is not null)
+        if (prepared.Bytes is not null)
         {
-            content.Headers.ContentType = string.IsNullOrEmpty(contentType)
+            var content = new ByteArrayContent(prepared.Bytes);
+            // Set the content type verbatim (no charset appended unless the caller added one).
+            content.Headers.ContentType = string.IsNullOrEmpty(prepared.ContentType)
                 ? null
-                : MediaTypeHeaderValue.Parse(contentType);
+                : MediaTypeHeaderValue.Parse(prepared.ContentType);
+            if (prepared.ContentEncoding is not null)
+            {
+                content.Headers.ContentEncoding.Add(prepared.ContentEncoding);
+            }
+
             request.Content = content;
         }
 
         return request;
     }
 
+    /// <summary>
+    /// Normalizes a request body to bytes and, when it is large enough, compresses it. Raw bytes take
+    /// precedence so binary records (e.g. images) are used as-is rather than re-encoded through a UTF-8
+    /// string; a string body is UTF-8 encoded. Either kind of payload is then compressed once it reaches
+    /// the size threshold (see the remarks).
+    /// </summary>
+    /// <remarks>
+    /// Bodies at or above <see cref="MinCompressBytes"/> are brotli-compressed (<c>Content-Encoding: br</c>),
+    /// matching the reference client, which prefers brotli and only falls back to gzip on runtimes where
+    /// brotli is unavailable. .NET's <see cref="BrotliStream"/> is always available, so brotli is always
+    /// used here and a gzip fallback would be unreachable.
+    /// </remarks>
+    private static PreparedBody PrepareBody(string? body, byte[]? bodyBytes, string contentType)
+    {
+        var raw = bodyBytes ?? (body is not null ? Encoding.UTF8.GetBytes(body) : null);
+        if (raw is null)
+        {
+            return default;
+        }
+
+        return raw.Length >= MinCompressBytes
+            ? new PreparedBody(BrotliCompress(raw), contentType, BrotliEncoding)
+            : new PreparedBody(raw, contentType, null);
+    }
+
+    /// <summary>Brotli-compresses a payload into a self-contained byte array.</summary>
+    private static byte[] BrotliCompress(byte[] data)
+    {
+        using var output = new MemoryStream();
+        using (var brotli = new BrotliStream(output, CompressionMode.Compress))
+        {
+            brotli.Write(data, 0, data.Length);
+        }
+
+        return output.ToArray();
+    }
+
+    /// <summary>
+    /// A request body normalized to bytes, together with the content type and optional
+    /// <c>Content-Encoding</c> to send. A <see langword="default"/> value carries no body.
+    /// </summary>
+    private readonly record struct PreparedBody(byte[]? Bytes, string ContentType, string? ContentEncoding);
+
     /// <summary>
     /// Returns <c>min(overall, base * 2^(attempt-1))</c>: the first attempt uses the base timeout; each
     /// retry doubles it (a slow-but-progressing connection gets more time) while never exceeding the

tests/Apify.Client.Tests/Unit/ConfigTests.cs

@@ -37,6 +37,22 @@ public void UserAgentIsAtHomeTrueAndSuffix()
         Assert.EndsWith("; my-suffix", client.UserAgent, System.StringComparison.Ordinal);
     }
 
+    [Fact]
+    public void UserAgentOsTokenUsesShortLowercasePlatformIdentifier()
+    {
+        // The OS token must be a short, lowercase platform identifier aligned with the other Apify
+        // clients' Node `os.platform()` values, not a uname-style name (e.g. "win32", never "windows").
+        var client = new ApifyClient(new ApifyClientOptions
+        {
+            Token = "t",
+            HttpTransport = new MockTransport(),
+        });
+
+        var osToken = Regex.Match(client.UserAgent, @"\(([^;]+);").Groups[1].Value;
+        Assert.Contains(osToken, new[] { "win32", "darwin", "linux", "android", "freebsd", "unknown" });
+        Assert.DoesNotContain("windows", client.UserAgent, System.StringComparison.Ordinal);
+    }
+
     [Fact]
     public void ApiBaseUrlAppendsV2()
     {