Product Changelog

Bug Fix:

• Resolved a security vulnerability.

Bug Fix:

• Upgraded org.jsoup:jsoup to 1.23.1 to fix a Cross-site Scripting (XSS) vulnerability.

Bug Fixes:

• Fixed a crash when logging requests whose URLs contain percent-encoded characters, caused by the log message being passed to the system logger as a format string.
• Fixed a runtime error when using the cacheThenNetwork cache policy with async/await. The policy now resolves once and falls back to cache-else-network.
• Fixed a per-request networkElseCache cache policy being ignored in favor of the stack-level policy when a transport error occurred.
• Fixed requests hanging indefinitely when a response returned neither data nor an error. These now fail with an invalid HTTP response error.

Bug Fix:

• Resolved a security vulnerability.

Bug Fixes:

• Upgraded @contentstack/core to ^1.5.1 to resolve MODULE_NOT_FOUND and "expression is too dynamic" build failures in bundlers such as Next.js Turbopack and webpack, caused by a dynamic require() call in the keep-alive agent setup. It now uses statically analyzable require('http') and require('https') calls.
• Guarded keep-alive agent creation for native ESM environments, where require is undefined, to prevent a ReferenceError.
• Added a package browser field mapping http/https so browser bundles resolve them cleanly.

Bug & Security Fixes:

• Updated dependencies in datasync-asset-store-filesystem (v2.3.8) to resolve security vulnerabilities.

New Feature:

• Added Taxonomy CDA support: fetch and query published taxonomies and terms with hierarchy traversal, localization, and fallback.

Bug & Security Fixes:

• Updated vulnerable dependency versions in contentstack.management.aspnetcore.csproj and test project files to resolve security vulnerabilities.
• Suppressed static-analysis alerts for hardcoded credentials in test files (integration and unit tests).

Bug & Security Fix:

• Resolved security vulnerabilities.

Bug & Security Fixes:

• Bumped @contentstack/core dependency to ^1.5.0, introducing the following stability improvements:
  • Added default retry logic for transient network-level errors (e.g., ECONNABORTED, ETIMEDOUT, ECONNRESET, EPIPE, EAI_AGAIN) when there is no HTTP response.
  • Implemented distinct classification for request timeouts instead of returning a generic UNKNOWN_ERROR.
  • Added default httpAgent and httpsAgent keep-alive connection agents in Node environments.

Bug & Security Fixes:

• Bumped setuptools minimum version from >=80.0.0,<82.0.0 to >=83.0.0 to resolve a security vulnerability finding.

Bug & Security Fixes:

• Upgraded setuptools to 83.0.0 to resolve an Improper Unicode Encoding Handling security issue.

Bug & Security Fixes:

• Upgraded black to >=26.3.1 to fix a high-severity Directory Traversal vulnerability.
• Upgraded pip to >=26.1.2 to fix Arbitrary File Upload, Arbitrary Code Injection, and Directory Traversal vulnerabilities.
• Upgraded setuptools to >=83.0.0 to fix an Improper Unicode Encoding Handling vulnerability.

Enhancements:

• Updated the contentType(...).entry(...).variants(variantUidOrUids, branchName?) method to accept an optional branchName as the second argument, which sets the CMA branch header for that variant's scope. The first argument supports either a single variant UID string or an array of UIDs (comma-separated in the request path). Omitting the branch name preserves the previous behavior.
• Added variants(uid).publish() and variants(uid).unpublish() methods, which call the entry publish and unpublish endpoints by nesting the variant payload under the entry.
• Updated the publish() and unpublish() methods (for both entries and entry variants) to accept optional headers and parameters, which are merged directly into the underlying HTTP request.
• Added unit and sanity API tests for entry variants with an explicit branch, as well as for the new variant publish and unpublish methods.

New Features:

• Added branch support in entry variants.

Enhancements:

• Updated the variants() method on Entry and Entries to support an optional branch name as the second argument. When provided, the branch is sent as a request header alongside x-cs-variant-uid.
• Ensured existing variants(uid) and variants(uids) calls remain backward compatible.
• Added unit and API tests to support variant and branch requests.

New Features:

• Added branch support in entry variants.

Enhancements:

• Added support for entry variants with optional branch scoping via the variants() method on Entry and Query.

Enhancements:

• Added the variants(variant_uids, branch_name) method to Contentstack::Entry and Contentstack::Query to fetch entry variants with optional per-request branch scoping. These requests now send the x-cs-variant-uid header (as comma-separated UIDs) and respect either the stack-level or per-call branch settings.

Bug Fix:

• Fixed an issue where the previously published 2.0.0 package did not include the EmbeddedObjectConverter. Bumped the package version to 2.0.1 and republished to ensure the published package matches the source code unambiguously.

Bug & Security Fix:

• Bumped the @contentstack/utils dependency from ^1.4.1 to ^1.9.1.

New Features:

• Added support for passing an optional branch parameter to the .Variant() method in both the Entry and Query classes to support Entry Variants branching.
• Implemented an automatic fallback to the Stack's configured branch or "main" if the branch parameter is null or empty.
• Added comprehensive unit and integration tests for the Entry and Query variant branch logic.

New Features:

• Added optional branch support for entry variants in the Entry.variants() and ContentType.variants() methods.

New Features:

• Added branch override support for Entry Variants. The Entry.Variant(uid?, branchUid?) method now accepts an optional branchUid to target a specific branch for variant calls (Find, Create, Update, Fetch, Delete) by overriding the branch request header. If null or empty, it falls back to the Stack's configured branch.
• Added publish and unpublish support for Entry Variants via EntryVariant.Publish/PublishAsync and EntryVariant.Unpublish/UnpublishAsync. These methods match the PublishUnpublishDetails contract used by Entry.Publish/Unpublish and respect the branch override.

New Features:

• Added publish and unpublish support for Entry Variants via the entry publish/unpublish endpoints, including documented payloads for entry.variants and optional entry.variant_rules on publish.
• Added optional stack branch support via the branch request header for Entry Variants. Entry.variants() now accepts no arguments, a branch UID only, or (variant_uid, branch) (use variants(variant_uid, None) when targeting a variant without a branch).

New Feature:

• Added branch support in entry variants.

New Feature:

• Added branch support in entry variants.

New Feature:

• Added support for Taxonomy Localization and Publishing.

Enhancement:

• Removed the locale parameter from Taxonomy.fetch() and Term.fetch().

New Feature:

• Added Taxonomy Publishing support to the Content Delivery SDK via stack.taxonomy().

Bug & Security Fix:

• Removed the unused keyring dependency to resolve a license-policy issue on the transitive secretstorage package.

Bug & Security Fix:

• Removed hardcoded password literals in unit tests to resolve CWE-798 (Use of Hardcoded Passwords) findings.

New Features:

• Added Branch management with Create, Fetch, Delete (including Async variants), and Query operations via Stack.Branch(uid?).
• Introduced multi-region endpoint resolution via Endpoint.GetContentstackEndpoint(region, service) supporting 7 regions (NA, EU, AU, Azure-NA, Azure-EU, GCP-NA, GCP-EU) and 18 service keys.
• Wired OAuth auto token refresh into the request pipeline.
• Added PreviewToken support for Create and Delete operations.
• Added image format upload coverage for JPEG, AVIF, and multi-format assets.

Enhancements:

• Upgraded the framework requirement to .NET 10 or later.
• Removed the Newtonsoft.Json dependency; all JSON serialization now uses System.Text.Json.
• Replaced client.SerializerSettings (JsonSerializerSettings) with client.SerializerOptions (JsonSerializerOptions).
• Removed response.OpenJObjectResponse() in favor of response.OpenJsonObjectResponse() (JsonObject) or response.OpenTResponse<T>().
• Updated JObjectParameterValue to accept System.Text.Json.Nodes.JsonNode instead of Newtonsoft.Json.Linq.JObject.
• Replaced all [JsonProperty] attributes with [JsonPropertyName].

New Features:

• Added support for the GCP_EU region.
• Added the Endpoint class for dynamic region-to-URL resolution via CDN-backed regions.json, and ContentstackRegionMap to map the ContentstackRegion enum to registry region IDs.
• Added ApiErrorBodyParser for consistent API error envelope parsing.
• Added JsonNodeConversion and JsonObjectMerge utilities to replace Newtonsoft equivalents.
• Added ContentstackJsonDefaults to provide shared JsonSerializerOptions across all custom converters.

Enhancements:

• Upgraded the framework requirement to .NET 10 or later.
• Removed the Newtonsoft.Json dependency; all JSON serialization now uses System.Text.Json (BCL).
• Migrated SDK methods to use JsonObject instead of JObject. Entry.ToJson(), Query.Count(), AssetLibrary.Count(), ContentType.Fetch(), GlobalField.Fetch(), and GlobalFieldQuery.Find() now return JsonObject.
• Updated AssetLibrary.Query() to accept JsonObject as its parameter.
• Replaced SerializerSettings with SerializerOptions and updated model classes to use [JsonPropertyName] instead of [JsonProperty].
• Updated Config.BaseUrl to resolve hosts from the regions registry, removing the hardcoded regionCode() and HostURL.
• Replaced Console.WriteLine with Debug.WriteLine in ContentstackConvert to suppress parse warnings from the application stdout.
• Updated the contentstack.utils dependency to v2.0.0 (final release).
• Replaced refresh-region.cs with refresh-region.py to prevent MSBuild from compiling the script as source, and added build/contentstack.csharp.targets to auto-deliver the script to consumer projects on their first build.
• Updated the .NET version in the SCA scan CI pipeline from 7.0.x to 10.0.x.
• Added EndpointTest.cs and added Assets/regions.json to .gitignore.

New Features:

• Introduced multi-region endpoint resolution via Endpoint.GetContentstackEndpoint(region, service), supporting 7 regions (NA, EU, AU, Azure-NA, Azure-EU, GCP-NA, GCP-EU) and 18 service keys.
• Added a proxy method Utils.GetContentstackEndpoint(region, service) to access endpoint resolution directly from the Utils class without needing to import Contentstack.Utils.Endpoints.
• Added the omitHttps flag to strip the https:// scheme from returned URLs, allowing for direct passing to SDK host configurations (e.g., new ContentstackOptions { Host = Endpoint.GetContentstackEndpoint("eu", "contentDelivery", omitHttps: true) }).
• Added case-insensitive region alias support (e.g., "us", "NA", "AWS-NA", and "azure_na" all resolve correctly to the same region).
• Implemented an auto-download and disk caching mechanism for the regions.json registry from the CDN on first use, requiring no setup. The SDK self-heals if the file is missing.
• Bundled Scripts/refresh-region.py inside the NuGet package, which automatically places the script in your project's Scripts/ folder upon the first dotnet build. You can run this script anytime to pull the latest regions from the CDN.

Breaking Changes:

• Upgraded the framework requirement to .NET 10 or later (previously netstandard2.0 / net6.0).
• Removed the Newtonsoft.Json package reference and replaced it with System.Text.Json across the entire package. Consuming projects must add System.Text.Json or rely on the BCL on supported runtimes.
• Updated GetVariantAliases() and GetVariantMetadataTags() methods to accept JsonObject / JsonArray instead of JObject / JArray.
• Deprecated GetDataCsvariantsAttribute(JObject/JArray, string), which now maps to JsonObject / JsonArray overloads.
• Updated Node.attrs values to use System.Text.Json.JsonElement instead of Newtonsoft.Json.Linq.JToken. (Note: Consuming code should update from node.attrs["src"].Value<string>() to node.attrs["src"].GetString()).
• Updated model classes to use [JsonPropertyName] instead of [JsonProperty].

Enhancements:

• Upgraded the target framework requirement to .NET 10.0 or later (previously .NET 7.0).
• Removed the Newtonsoft.Json dependency entirely. Migrated the tool's internals, model DTOs, OAuth service, the HTTP layer, and ContentstackClient to use System.Text.Json.
• Updated code-generation templates so that generated model files now use [JsonPropertyName] and generated converters inherit System.Text.Json.Serialization.JsonConverter<T>.

Note: Regenerating models against an existing project will change these attributes and converters, so consuming code must be updated accordingly.

• Removed support for legacy BinaryFormatter-based serialization in ContentstackException.
• Updated reference-field type resolution to use System.Text.Json.JsonElement instead of the removed Newtonsoft types.
• Updated the CI/CD pipeline to use the .NET 10 SDK and upgraded Microsoft.AspNetCore.Mvc.Testing to version 10.0.0.

Bug & Security Fixes:

• Fixed a template bug where the generated embeddedItems property's nullable annotation was incorrectly emitted as literal text ({nullableString()}) for content types with RTE-embedded references.
• Fixed the GetHeader method visibility (changed from private to internal) to allow test access.

Bug & Security Fixes:

• Fixed Asset.update() to send the JSON body with Content-Type: application/json instead of an invalid bare multipart/form-data, preventing 422 API rejections.
• Fixed Asset.replace() to allow the HTTP layer to set multipart/form-data with a proper boundary, resolving 422 errors caused by a missing boundary.
• Resolved a side effect in both Asset.update() and Asset.replace() that leaked the incorrect Content-Type onto subsequent requests.

Enhancement

• Dynamic Region Endpoint Resolution: Introduced Endpoint.getContentstackEndpoint to dynamically resolve service endpoints from the centralized Contentstack Regions Registry. This implementation features alias-aware, case-insensitive evaluation and throws an explicit Endpoint.EndpointError upon encountering invalid input.

New Features

• Dynamic Region Endpoint Resolution: Introduced ContentstackUtils::Endpoint.get_contentstack_endpoint to enable dynamic URL routing based on specified region and service configurations.
• Endpoint Resolution Proxy: Added ContentstackUtils.get_contentstack_endpoint as a top-level module proxy to maintain backward compatibility with existing integration patterns.
• Automated Runtime Fallback: Integrated a runtime synchronization mechanism that automatically downloads the regions.json manifest from the Contentstack Regions Registry if the file is not present in the local cache.
• Manual Registry Synchronization: Added ContentstackUtils::Endpoint.refresh_regions to facilitate the manual retrieval and refreshing of localized region metadata.

Security and Bug Fixes

• Dependency Vulnerability Patches: Upgraded critical project dependencies to resolve established security risks:
  • Upgraded yard to 0.9.44 to address a Directory Traversal vulnerability.
  • Upgraded concurrent-ruby to 1.3.7 to fix issues relating to infinite loops, improper locking, and wrap-around errors.

Bug Fixes

• Polymorphic JSON Deserialization: Introduced EmbeddedObject as a concrete implementation of IEmbeddedObject to seamlessly cover both IEmbeddedEntry and IEmbeddedAsset contracts during JSON deserialization.
• Custom Type Conversion: Implemented EmbeddedObjectConverter to resolve polymorphic IEmbeddedObject types automatically during deserialization, eliminating the need for breaking changes in consumer code.
• Metadata and Custom Field Retention: Applied the [JsonExtensionData] attribute to ensure that all custom, unmapped fields on embedded entries and assets are fully preserved without data loss.

Bug Fixes

• Automated Embedded Items Deserialization: Registered the EmbeddedObjectConverter directly within the ContentstackClient constructor. This ensures that .includeEmbeddedItems().Fetch<T>() successfully deserializes the _embedded_items payload when the target model implements IEntryEmbedable, without requiring any architectural changes in consumer code.
• Core Dependency Upgrade: Upgraded the downstream utility dependency from contentstack.utils 1.3.0 to contentstack.utils 1.4.0 to import the new concrete EmbeddedObject class and the updated EmbeddedObjectConverter.

New Features

• Dynamic Region Endpoint Resolution: Introduced Endpoint.getContentstackEndpoint() to enable dynamic service URL routing driven by the centralized Contentstack Regions Registry.
• Endpoint Resolution Proxy: Added Utils.getContentstackEndpoint() as a top-level proxy method to ensure backward-compatible access through the existing utility path.
• Automated Registry Provisioning: Integrated a dual-phase registry mechanism where regions.json is automatically downloaded at build time via scripts/download-regions.sh, supplemented by a fail-safe runtime fallback to fetch the manifest if the local file is missing.

Enhancement

• Dynamic Region Endpoint Resolution: Implemented dynamic endpoint routing powered by the centralized Contentstack Regions Registry. Developers can now utilize Endpoint.getContentstackEndpoint() and the configured Builder.setRegion() mechanism to resolve service URLs automatically across all supported environments.

Enhancements

• Dynamic Region Endpoint Resolution: Implemented dynamic endpoint routing powered by the centralized Contentstack Regions Registry. Developers can now utilize Endpoint.getContentstackEndpoint() and the configured Builder.setRegion() mechanism to resolve service URLs automatically across all supported environments.

Enhancements

• Region Refresh Script Migration: Replaced Scripts/refresh-region.cs with a Python implementation (Scripts/refresh-region.py) to prevent MSBuild from incorrectly compiling the script as source code.
• macOS SSL Fallback: Integrated an SSL fallback mechanism within the refresh-region.py script to mitigate macOS certificate verification failures.
• Project Configuration Updates: Updated both contentstack.management.csharp.targets and contentstack.management.core.csproj to package and deliver the new Python script.
• Image Format Upload Test Coverage: Expanded test coverage under Contentstack.Management.Core.Tests/Mock/assets/ to ensure SDK stability across various image types:
  • Test100 (JPEG Upload): Validates the upload of london.jpg via image/jpeg MIME type, asserting the Created status and content_type in the response.
  • Test101 (JPEG Extension Upload): Validates the upload of tokyo.jpeg and asserts the image/jpeg content type.
  • Test102 (AVIF Upload): Validates the upload of dubai.avif via image/avif MIME type, accepting either image/avif or application/octet-stream content types.
  • Test103 (Sequential Uploads): Validates sequential uploads of all three image formats and asserts the Created status for each.
  • Test104 (Metadata Retrieval): Verifies the ability to fetch metadata for a created JPEG asset, asserting the presence of uid, filename, content_type, and file_size fields.
  • Test105 (Asset Updates): Verifies asset replacement functionality by overwriting an existing JPEG asset and asserting a 200 OK update response.

Bug Fixes

• Bulk Operation Test Assertions: Updated bulk operation tests to accept a 401 Unauthorized status alongside existing 404 / 400 codes for invalid or expired job ID assertions.
• Resilient Test Workflows: Configured workflow stage assignments in Test002 to be non-fatal, preventing bulk operation test failures when the workflow API is temporarily unavailable.

New Features

• Dynamic Region Resolution: Introduced an Endpoint class to enable dynamic region-to-URL resolution utilizing a CDN-backed regions.json file.
• Region Mapping: Added ContentstackRegionMap to map the ContentstackRegion enum directly to registry region IDs.
• GCP EU Support: Expanded infrastructure support to include the GCP_EU region.

Enhancements

• Dynamic Base URL Configuration: Updated Config.BaseUrl to resolve hosts dynamically via the regions registry, removing the hardcoded regionCode() and HostURL logic.
• Region Refresh Script Migration: Replaced refresh-region.cs with a Python implementation (refresh-region.py) to prevent MSBuild from incorrectly compiling the script as source code.
• Build Targets Automation: Added build/contentstack.csharp.targets to automatically package and deliver the refresh-region.py script to consumer projects upon their first build.
• Automated Test Coverage: Implemented EndpointTest.cs to ensure the reliability and coverage of the new endpoint resolution logic.

New Features

• Dynamic Region Resolution: Introduced an Endpoint class to enable dynamic region-to-URL resolution utilizing a CDN-backed regions.json file.
• Region Mapping: Added ContentstackRegionMap to map the ContentstackRegion enum directly to registry region IDs.
• GCP EU Support: Expanded infrastructure support to include the GCP_EU region.

Enhancements

• Dynamic Base URL Configuration: Updated Config.BaseUrl to resolve hosts dynamically via the regions registry, removing the hardcoded regionCode() and HostURL logic.
• Region Refresh Script Migration: Replaced refresh-region.cs with a Python implementation (refresh-region.py) to prevent MSBuild from incorrectly compiling the script as source code.
• Build Targets Automation: Added build/contentstack.csharp.targets to automatically package and deliver the refresh-region.py script to consumer projects upon their first build.
• Automated Test Coverage: Implemented EndpointTest.cs to ensure the reliability and coverage of the new endpoint resolution logic.

New Features

• Dynamic Region Resolution: Introduced Endpoint.get_contentstack_endpoint() to enable dynamic, region-aware URL resolution across all supported Contentstack regions and services.
• Endpoint Resolution Proxy: Added Utils.get_contentstack_endpoint() as a top-level proxy method to ensure backward-compatible access via the existing Utils import path.
• Cross-SDK Parity Aliases: Added getContentstackEndpoint camelCase aliases to both the Endpoint and Utils classes for consistent interface parity across different Contentstack SDKs.
• Automated Registry Provisioning and Fallback: Bundled the authoritative regions.json registry file (supporting 7 regions and 18 service endpoint keys) into contentstack_utils/assets/regions.json. Implemented a runtime fallback mechanism in Endpoint._load_regions() that automatically downloads the registry from the Contentstack artifact server on first use if the local file is missing.
• Programmatic and CLI Registry Synchronization: Added a refresh_regions() utility—exposed at the package level—and a python3 -m contentstack_utils.region_refresh CLI command to allow developers to programmatically or manually fetch the latest regions manifest from the CDN and overwrite the local cache.

Enhancements

• Package-Level Exports: Exposed the Endpoint class within the package-level __all__ export list for simplified imports.
• Automated Build-Time Refresh: Updated setup.py with a custom BuildPyWithRegions command to automatically refresh regions.json at build time. Network failures during this step are captured as warnings and will not block the build process.
• Package Data Distribution: Added assets/regions.json to the package_data configuration in setup.py, ensuring the registry file is correctly bundled and shipped within the source distribution and wheel formats.
• Source-Tree Utility: Bundled scripts/refresh_regions.py into the source tree for standalone environment utilization.

New Features

• Dynamic Region Endpoint Resolution: Implemented dynamic region endpoint resolution powered by the centralized Contentstack Regions Registry (regions.json). This ensures that new regions and services can be supported via registry updates without requiring SDK code changes.
• Three-Tier Endpoint Resolution: Introduced the Endpoint class featuring a robust three-tier resolution architecture that checks an in-memory cache, falls back to the bundled data/regions.json file, and performs a live CDN download if necessary.
• Module-Level Proxy: Exposed contentstack_management.get_contentstack_endpoint(region, service, omit_https) as a top-level module proxy for streamlined endpoint resolution.

Enhancements

• Dynamic Client Routing: Updated the base Client logic to dynamically resolve the contentManagement endpoint directly from the registry, completely removing the legacy hardcoded host pattern.
• Registry Refresh Script: Bundled scripts/download_regions.py into the repository to allow manual or automated synchronization of the bundled registry file with the live CDN.