Merge pull request #61 from ChangemakerStudios/feature/Cookies

Add strongly-typed cookie support for Gotenberg API. Addresses issue #59.

Author: Jaben

lib/Domain/Builders/Faceted/DocumentBuilder.cs

@@ -26,9 +26,7 @@ public sealed class DocumentBuilder
 
     public DocumentBuilder(FullDocument content, Action<bool> setContainsMarkdown)
     {
-        if (content == null) throw new ArgumentNullException(nameof(content));
-
-        this._content = content;
+        this._content = content ?? throw new ArgumentNullException(nameof(content));
         this._setContainsMarkdown = setContainsMarkdown;
     }
 

lib/Domain/Builders/Faceted/HtmlConversionBehaviorBuilder.cs

@@ -23,7 +23,7 @@ public sealed class HtmlConversionBehaviorBuilder
 
     internal HtmlConversionBehaviorBuilder(HtmlConversionBehaviors htmlConversionBehaviors)
     {
-        this._htmlConversionBehaviors = htmlConversionBehaviors;
+        _htmlConversionBehaviors = htmlConversionBehaviors;
     }
 
     /// <summary>
@@ -34,7 +34,7 @@ internal HtmlConversionBehaviorBuilder(HtmlConversionBehaviors htmlConversionBeh
     /// <remarks>Prefer <see cref="SetBrowserWaitExpression" /> over waitDelay.</remarks>
     public HtmlConversionBehaviorBuilder SetBrowserWaitDelay(int seconds)
     {
-        this._htmlConversionBehaviors.WaitDelay = $"{seconds}s";
+        _htmlConversionBehaviors.WaitDelay = $"{seconds}s";
 
         return this;
     }
@@ -49,9 +49,12 @@ public HtmlConversionBehaviorBuilder SetBrowserWaitDelay(int seconds)
     /// <exception cref="InvalidOperationException"></exception>
     public HtmlConversionBehaviorBuilder SetBrowserWaitExpression(string expression)
     {
-        if (expression.IsNotSet()) throw new InvalidOperationException("expression is not set");
+        if (expression.IsNotSet())
+        {
+            throw new InvalidOperationException("expression is not set");
+        }
 
-        this._htmlConversionBehaviors.WaitForExpression = expression;
+        _htmlConversionBehaviors.WaitForExpression = expression;
 
         return this;
     }
@@ -65,9 +68,12 @@ public HtmlConversionBehaviorBuilder SetBrowserWaitExpression(string expression)
     [Obsolete("Deprecated in Gotenberg v8+")]
     public HtmlConversionBehaviorBuilder SetUserAgent(string userAgent)
     {
-        if (userAgent.IsNotSet()) throw new InvalidOperationException("headerName is not set");
+        if (userAgent.IsNotSet())
+        {
+            throw new InvalidOperationException("headerName is not set");
+        }
 
-        this._htmlConversionBehaviors.UserAgent = userAgent;
+        _htmlConversionBehaviors.UserAgent = userAgent;
 
         return this;
     }
@@ -84,7 +90,7 @@ public HtmlConversionBehaviorBuilder AddAdditionalHeaders(string headerName, str
     {
         var header = string.Format("{0}{2}{1}", "{", "}", $"{'"'}{headerName}{'"'} : {'"'}{headerValue}{'"'}");
 
-        return this.AddAdditionalHeaders(JObject.Parse(header));
+        return AddAdditionalHeaders(JObject.Parse(header));
     }
 
     /// <summary>
@@ -95,16 +101,42 @@ public HtmlConversionBehaviorBuilder AddAdditionalHeaders(string headerName, str
     /// <exception cref="InvalidOperationException"></exception>
     public HtmlConversionBehaviorBuilder AddAdditionalHeaders(JObject extraHeaders)
     {
-        if (extraHeaders == null) throw new InvalidOperationException("headerValue is null");
+        if (extraHeaders == null)
+        {
+            throw new InvalidOperationException("extraHeaders is null");
+        }
 
-        this._htmlConversionBehaviors.ExtraHeaders = extraHeaders;
+        _htmlConversionBehaviors.ExtraHeaders = extraHeaders;
 
         return this;
     }
 
     /// <summary>
-    /// Sets the document metadata.
-    /// Not all metadata are writable. Consider taking a look at https://exiftool.org/TagNames/XMP.html#pdf for an (exhaustive?) list of available metadata.
+    ///     Adds a cookie to store in the Chromium cookie jar.
+    /// </summary>
+    /// <param name="cookie">The cookie to add</param>
+    /// <returns></returns>
+    /// <exception cref="ArgumentNullException"></exception>
+    public HtmlConversionBehaviorBuilder AddCookie(Cookie cookie)
+    {
+        if (cookie == null)
+        {
+            throw new ArgumentNullException(nameof(cookie));
+        }
+
+        _htmlConversionBehaviors.Cookies ??= new List<Cookie>();
+
+        Cookie.Validate(cookie);
+
+        _htmlConversionBehaviors.Cookies.Add(cookie);
+
+        return this;
+    }
+
+    /// <summary>
+    ///     Sets the document metadata.
+    ///     Not all metadata are writable. Consider taking a look at https://exiftool.org/TagNames/XMP.html#pdf for an
+    ///     (exhaustive?) list of available metadata.
     /// </summary>
     /// <param name="dictionary"></param>
     /// <returns></returns>
@@ -116,16 +148,20 @@ public HtmlConversionBehaviorBuilder SetMetadata(IDictionary<string, object> dic
     }
 
     /// <summary>
-    /// Sets the document metadata.
-    /// Not all metadata are writable. Consider taking a look at https://exiftool.org/TagNames/XMP.html#pdf for an (exhaustive?) list of available metadata.
+    ///     Sets the document metadata.
+    ///     Not all metadata are writable. Consider taking a look at https://exiftool.org/TagNames/XMP.html#pdf for an
+    ///     (exhaustive?) list of available metadata.
     /// </summary>
     /// <param name="metadata"></param>
     /// <returns></returns>
     public HtmlConversionBehaviorBuilder SetMetadata(JObject metadata)
     {
-        if (metadata == null) throw new InvalidOperationException("metadata is null");
+        if (metadata == null)
+        {
+            throw new InvalidOperationException("metadata is null");
+        }
 
-        this._htmlConversionBehaviors.MetaData = metadata;
+        _htmlConversionBehaviors.MetaData = metadata;
 
         return this;
     }
@@ -136,7 +172,7 @@ public HtmlConversionBehaviorBuilder SetMetadata(JObject metadata)
     /// <returns></returns>
     public HtmlConversionBehaviorBuilder FailOnConsoleExceptions()
     {
-        this._htmlConversionBehaviors.FailOnConsoleExceptions = true;
+        _htmlConversionBehaviors.FailOnConsoleExceptions = true;
 
         return this;
     }
@@ -147,18 +183,18 @@ public HtmlConversionBehaviorBuilder FailOnConsoleExceptions()
     /// <returns></returns>
     public HtmlConversionBehaviorBuilder EmulateAsScreen()
     {
-        this._htmlConversionBehaviors.EmulatedMediaType = "screen";
+        _htmlConversionBehaviors.EmulatedMediaType = "screen";
 
         return this;
     }
 
     /// <summary>
-    ///     Gotenberg 8+ ONLY: Configures gotenberg to not wait for Chromium network to be idle. 
+    ///     Gotenberg 8+ ONLY: Configures gotenberg to not wait for Chromium network to be idle.
     /// </summary>
     /// <returns></returns>
     public HtmlConversionBehaviorBuilder SkipNetworkIdleEvent()
     {
-        this._htmlConversionBehaviors.SkipNetworkIdleEvent = true;
+        _htmlConversionBehaviors.SkipNetworkIdleEvent = true;
 
         return this;
     }
@@ -171,9 +207,12 @@ public HtmlConversionBehaviorBuilder SkipNetworkIdleEvent()
     /// <exception cref="InvalidOperationException"></exception>
     public HtmlConversionBehaviorBuilder SetPdfFormat(ConversionPdfFormats format)
     {
-        if (format == default) throw new InvalidOperationException("Invalid PDF format specified");
+        if (format == default)
+        {
+            throw new InvalidOperationException("Invalid PDF format specified");
+        }
 
-        this._htmlConversionBehaviors.PdfFormat = format;
+        _htmlConversionBehaviors.PdfFormat = format;
 
         return this;
     }
@@ -183,7 +222,7 @@ public HtmlConversionBehaviorBuilder SetPdfFormat(ConversionPdfFormats format)
     /// </summary>
     public HtmlConversionBehaviorBuilder SetPdfUa(bool enablePdfUa = true)
     {
-        this._htmlConversionBehaviors.EnablePdfUa = enablePdfUa;
+        _htmlConversionBehaviors.EnablePdfUa = enablePdfUa;
 
         return this;
     }

lib/Domain/Builders/Faceted/HtmlConversionBehaviorBuilderExtensions.cs

@@ -0,0 +1,86 @@
+// Copyright 2019-2025 Chris Mohan, Jaben Cargman
+//  and GotenbergSharpApiClient Contributors
+// 
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+// 
+//      http://www.apache.org/licenses/LICENSE-2.0
+// 
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+namespace Gotenberg.Sharp.API.Client.Domain.Builders.Faceted;
+
+public static class HtmlConversionBehaviorBuilderExtensions
+{
+    /// <summary>
+    ///     Adds a cookie to store in the Chromium cookie jar.
+    /// </summary>
+    /// <param name="builder">HtmlConversionBehaviorBuilder</param>
+    /// <param name="name">Cookie name</param>
+    /// <param name="value">Cookie value</param>
+    /// <param name="domain">Cookie domain</param>
+    /// <param name="path">Optional cookie path</param>
+    /// <param name="secure">Optional secure flag</param>
+    /// <param name="httpOnly">Optional HTTP-only flag</param>
+    /// <param name="sameSite">Optional SameSite attribute ("Strict", "Lax", or "None")</param>
+    /// <returns></returns>
+    public static HtmlConversionBehaviorBuilder AddCookie(this HtmlConversionBehaviorBuilder builder,
+        string name,
+        string value,
+        string domain,
+        string? path = null,
+        bool? secure = null,
+        bool? httpOnly = null,
+        string? sameSite = null)
+    {
+        if (builder == null)
+        {
+            throw new ArgumentNullException(nameof(builder));
+        }
+
+        var cookie = new Cookie
+        {
+            Name = name,
+            Value = value,
+            Domain = domain,
+            Path = path,
+            Secure = secure,
+            HttpOnly = httpOnly,
+            SameSite = sameSite
+        };
+
+        return builder.AddCookie(cookie);
+    }
+
+    /// <summary>
+    ///     Adds multiple cookies to store in the Chromium cookie jar.
+    /// </summary>
+    /// <param name="builder">HtmlConversionBehaviorBuilder</param>
+    /// <param name="cookies">The cookies to add</param>
+    /// <returns></returns>
+    /// <exception cref="ArgumentNullException"></exception>
+    public static HtmlConversionBehaviorBuilder AddCookies(this HtmlConversionBehaviorBuilder builder, IEnumerable<Cookie> cookies)
+    {
+        if (builder == null)
+        {
+            throw new ArgumentNullException(nameof(builder));
+        }
+
+        if (cookies == null)
+        {
+            throw new ArgumentNullException(nameof(cookies));
+        }
+
+        foreach (var c in cookies)
+        {
+            builder.AddCookie(c);
+        }
+
+        return builder;
+    }
+}

lib/Domain/Requests/Facets/Cookie.cs

@@ -0,0 +1,74 @@
+// Copyright 2019-2025 Chris Mohan, Jaben Cargman
+//  and GotenbergSharpApiClient Contributors
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+
+using Newtonsoft.Json;
+
+namespace Gotenberg.Sharp.API.Client.Domain.Requests.Facets;
+
+/// <summary>
+/// Represents a cookie to store in the Chromium cookie jar.
+/// See https://gotenberg.dev/docs/routes#cookies-chromium for details.
+/// </summary>
+public sealed record Cookie
+{
+    /// <summary>
+    /// Cookie name (required)
+    /// </summary>
+    [JsonProperty("name")]
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// Cookie value (required)
+    /// </summary>
+    [JsonProperty("value")]
+    public required string Value { get; init; }
+
+    /// <summary>
+    /// Cookie domain (required)
+    /// </summary>
+    [JsonProperty("domain")]
+    public required string Domain { get; init; }
+
+    /// <summary>
+    /// Cookie path (optional)
+    /// </summary>
+    [JsonProperty("path", NullValueHandling = NullValueHandling.Ignore)]
+    public string? Path { get; init; }
+
+    /// <summary>
+    /// Set cookie as secure (optional)
+    /// </summary>
+    [JsonProperty("secure", NullValueHandling = NullValueHandling.Ignore)]
+    public bool? Secure { get; init; }
+
+    /// <summary>
+    /// Set cookie as HTTP-only (optional)
+    /// </summary>
+    [JsonProperty("httpOnly", NullValueHandling = NullValueHandling.Ignore)]
+    public bool? HttpOnly { get; init; }
+
+    /// <summary>
+    /// SameSite attribute. Accepted values: "Strict", "Lax", or "None" (optional)
+    /// </summary>
+    [JsonProperty("sameSite", NullValueHandling = NullValueHandling.Ignore)]
+    public string? SameSite { get; init; }
+
+    public static void Validate(Cookie cookie)
+    {
+        if (cookie.Name.IsNotSet()) throw new ArgumentException("Cookie.Name must not be null or empty", nameof(cookie.Name));
+        if (cookie.Value.IsNotSet()) throw new ArgumentException("Cookie.Value must not be null or empty", nameof(cookie.Value));
+        if (cookie.Domain.IsNotSet()) throw new ArgumentException("Cookie.Domain must not be null or empty", nameof(cookie.Domain));
+    }
+}