Modernization

Directory.Build.props

@@ -1,7 +1,39 @@
 <Project>
   <PropertyGroup>
     <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <!-- Enable CI-specific deterministic/source-linked builds when running in CI -->
+    <ContinuousIntegrationBuild Condition="'$(CI)'=='true'">true</ContinuousIntegrationBuild>
   </PropertyGroup>
+
+  <!-- Shared packaging and SourceLink configuration for packable projects only -->
+  <PropertyGroup Condition="'$(IsPackable)'=='true'">
+    <GenerateAssemblyInfo>true</GenerateAssemblyInfo>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <PublishRepositoryUrl>true</PublishRepositoryUrl>
+    <IncludeSymbols>true</IncludeSymbols>
+    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+    <EmbedUntrackedSources>true</EmbedUntrackedSources>
+
+    <Authors>Kontent s.r.o.</Authors>
+    <Product>Kontent.ai</Product>
+    <Copyright>© 2025 Kontent s.r.o. All rights reserved.</Copyright>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageProjectUrl>https://github.com/kontent-ai/delivery-sdk-net</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/kontent-ai/delivery-sdk-net.git</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+
+    <!-- Prefer embedded icon/readme over legacy URL -->
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageIcon>kai-logo-symbol-color-rgb.png</PackageIcon>
+  </PropertyGroup>
+
+  <ItemGroup Condition="'$(IsPackable)'=='true'">
+    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="All" />
+    <None Include="../README.md" Pack="true" PackagePath="" />
+    <None Include="../kai-logo-symbol-color-rgb.png" Pack="true" PackagePath="" />
+  </ItemGroup>
 </Project>

Kontent.Ai.Delivery.Abstractions.Tests/CheckNamespaces.cs

@@ -1,20 +1,13 @@
-using System;
-using System.Linq;
 using System.Reflection;
 using System.Runtime.CompilerServices;
 using Xunit;
 using Xunit.Abstractions;
 
-namespace Kontent.Ai.Delivery.Abstractions.Tests;
+namespace Kontent.Ai.Delivery.Abstractions;
 
-public class CheckNamespaces
+public class CheckNamespaces(ITestOutputHelper output)
 {
-    private readonly ITestOutputHelper output;
-
-    public CheckNamespaces(ITestOutputHelper output)
-    {
-        this.output = output;
-    }
+    private readonly ITestOutputHelper output = output;
 
     /// <summary>
     /// See Kontent.Ai.Delivery.Abstractions Readme for more information.
@@ -24,8 +17,16 @@ public void AllNamespacecAreCorrect()
     {
         var abstractionTypes = Assembly.LoadFrom("Kontent.Ai.Delivery.Abstractions.dll");
 
+        var typesToCheck = abstractionTypes
+            .GetTypes()
+            // Exclude compiler-generated artifacts and synthesized types
+            .Where(t => t.GetCustomAttribute(typeof(CompilerGeneratedAttribute), inherit: true) == null)
+            .Where(t => !t.Name.StartsWith("<>"))
+            // Only consider types that actually have a namespace
+            .Where(t => t.Namespace is not null);
+
         Assert.All(
-            abstractionTypes.GetTypes().Where(t => t.GetCustomAttribute(typeof(CompilerGeneratedAttribute), true) == null),
-            t => Assert.Equal("Kontent.Ai.Delivery.Abstractions", t.Namespace));
+            typesToCheck,
+            t => Assert.StartsWith("Kontent.Ai.Delivery.Abstractions", t.Namespace));
     }
 }

Kontent.Ai.Delivery.Abstractions.Tests/Kontent.Ai.Delivery.Abstractions.Tests.csproj

@@ -6,13 +6,13 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
-    <PackageReference Include="xunit" Version="2.9.2" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2">
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>
-    <PackageReference Include="coverlet.collector" Version="3.1.2">
+    <PackageReference Include="coverlet.collector" Version="3.2.0">
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>

Kontent.Ai.Delivery.Abstractions/Caching/IDeliveryCacheManager.cs

@@ -0,0 +1,108 @@
+namespace Kontent.Ai.Delivery.Abstractions;
+
+/// <summary>
+/// Manages caching of Delivery API responses with automatic dependency tracking and invalidation.
+/// Implementations should provide thread-safe operations suitable for concurrent access.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This interface follows modern .NET caching patterns, separating retrieval (<see cref="GetAsync{T}"/>),
+/// storage (<see cref="SetAsync{T}"/>), and invalidation (<see cref="InvalidateAsync"/>) concerns.
+/// </para>
+/// <para>
+/// The dependency tracking system enables automatic cache invalidation when content changes.
+/// When storing a cache entry, you specify which content items, assets, or taxonomies it depends on.
+/// Later, calling <see cref="InvalidateAsync"/> with any of those dependency keys will invalidate
+/// all cache entries that reference them.
+/// </para>
+/// <para>
+/// Dependency key format conventions:
+/// <list type="bullet">
+/// <item><description>Content items: <c>item_{codename}</c> (e.g., "item_hero")</description></item>
+/// <item><description>Assets: <c>asset_{guid}</c> (e.g., "asset_a5e1c4b2-...")</description></item>
+/// <item><description>Taxonomies: <c>taxonomy_{group}</c> (e.g., "taxonomy_categories")</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+public interface IDeliveryCacheManager
+{
+    /// <summary>
+    /// Attempts to retrieve a cached value by its key.
+    /// </summary>
+    /// <typeparam name="T">The type of the cached value.</typeparam>
+    /// <param name="cacheKey">The unique key identifying the cache entry.</param>
+    /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+    /// <returns>
+    /// A task representing the asynchronous operation, containing the cached value if found;
+    /// otherwise, <c>null</c>.
+    /// </returns>
+    /// <remarks>
+    /// This method should return <c>null</c> for cache misses or expired entries, not throw exceptions.
+    /// Implementations should handle deserialization errors gracefully by treating them as cache misses.
+    /// </remarks>
+    Task<T?> GetAsync<T>(string cacheKey, CancellationToken cancellationToken = default) where T : class;
+
+    /// <summary>
+    /// Stores a value in the cache with associated dependency keys for automatic invalidation.
+    /// </summary>
+    /// <typeparam name="T">The type of the value to cache.</typeparam>
+    /// <param name="cacheKey">The unique key under which to store the value. Must not be <c>null</c> or empty.</param>
+    /// <param name="value">The value to cache. Must not be <c>null</c>.</param>
+    /// <param name="dependencies">
+    /// A collection of dependency keys that, when invalidated, will also invalidate this cache entry.
+    /// Use standardized key formats (see <see cref="IDeliveryCacheManager"/> remarks).
+    /// Must not be <c>null</c>, but may be empty.
+    /// </param>
+    /// <param name="expiration">
+    /// Optional absolute expiration timespan. If <c>null</c>, the implementation's default expiration is used.
+    /// </param>
+    /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+    /// <returns>A task representing the asynchronous storage operation.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="cacheKey"/>, <paramref name="value"/>, or <paramref name="dependencies"/> is <c>null</c>.
+    /// </exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="cacheKey"/> is empty or whitespace.
+    /// </exception>
+    /// <remarks>
+    /// <para>
+    /// Implementations should create a reverse index mapping each dependency key to all cache entries
+    /// that reference it, enabling efficient invalidation via <see cref="InvalidateAsync"/>.
+    /// </para>
+    /// <para>
+    /// If the cache write fails, implementations should throw an exception rather than silently fail,
+    /// allowing the calling code to handle the error appropriately.
+    /// </para>
+    /// </remarks>
+    Task SetAsync<T>(
+        string cacheKey,
+        T value,
+        IEnumerable<string> dependencies,
+        TimeSpan? expiration = null,
+        CancellationToken cancellationToken = default) where T : class;
+
+    /// <summary>
+    /// Invalidates all cache entries that depend on the specified dependency keys.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+    /// <param name="dependencyKeys">
+    /// One or more dependency keys to invalidate. All cache entries referencing any of these keys
+    /// will be removed from the cache.
+    /// </param>
+    /// <returns>A task representing the asynchronous invalidation operation.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method performs cascade invalidation: if a cache entry depends on any of the specified keys,
+    /// it will be removed, regardless of what other dependencies it may have.
+    /// </para>
+    /// <para>
+    /// Invalidating a non-existent dependency key should succeed without error (idempotent operation).
+    /// </para>
+    /// <para>
+    /// Example: If a cached items list depends on "item_hero" and "item_author", calling
+    /// <c>InvalidateAsync(dependencyKeys: "item_hero")</c> will invalidate the entire list,
+    /// even though "item_author" was not invalidated.
+    /// </para>
+    /// </remarks>
+    Task InvalidateAsync(CancellationToken cancellationToken = default, params string[] dependencyKeys);
+}