Pin API alignment: option and response records, streaming/progress options

src/CoreApi/AddFileOptions.cs

@@ -17,6 +17,14 @@ public class AddFileOptions
         /// </value>
         public bool? Pin { get; set; }
 
+        /// <summary>
+        ///   Optional name to assign to the pin when pinning during add (Kubo v0.37.0+).
+        /// </summary>
+        /// <remarks>
+        ///   Forwarded as the 'pin-name' parameter to the add RPC. Effective when pinning is enabled.
+        /// </remarks>
+        public string? PinName { get; set; }
+
         /// <summary>
         ///   Chunking algorithm, size-[bytes], rabin-[min]-[avg]-[max] or buzhash. Required: no.
         /// </summary>

src/CoreApi/BlocksPinnedProgress.cs

@@ -0,0 +1,12 @@
+namespace Ipfs.CoreApi;
+
+/// <summary>
+///   Progress notification for pin/add reporting cumulative blocks pinned.
+/// </summary>
+public record BlocksPinnedProgress
+{
+    /// <summary>
+    ///   The cumulative number of blocks pinned so far.
+    /// </summary>
+    public int BlocksPinned { get; init; }
+}

src/CoreApi/IPinApi.cs

@@ -1,6 +1,9 @@
 using System.Collections.Generic;
+using System.Collections;
 using System.Threading;
 using System.Threading.Tasks;
+using System.Runtime.CompilerServices;
+using System;
 
 namespace Ipfs.CoreApi
 {
@@ -17,9 +20,8 @@ public interface IPinApi
         ///   A CID or path to an existing object, such as "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about"
         ///   or "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V"
         /// </param>
-        /// <param name="recursive">
-        ///   <b>true</b> to recursively pin links of the object; otherwise, <b>false</b> to only pin
-        ///   the specified object.  Default is <b>true</b>.
+        /// <param name="options">
+        ///   Options for pinning (name and recursion). If null, defaults are used.
         /// </param>
         /// <param name="cancel">
         ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
@@ -28,19 +30,26 @@ public interface IPinApi
         ///   A task that represents the asynchronous operation. The task's value
         ///   is a sequence of <see cref="Cid"/> that were pinned.
         /// </returns>
-        Task<IEnumerable<Cid>> AddAsync(string path, bool recursive = true, CancellationToken cancel = default);
+        Task<IEnumerable<Cid>> AddAsync(string path, PinAddOptions options, CancellationToken cancel = default);
+
+        /// <summary>
+        ///   Adds an IPFS object to the pinset with progress reporting.
+        /// </summary>
+        /// <param name="path">The CID or path of the object to pin.</param>
+        /// <param name="options">Options for pinning (name and recursion).</param>
+        /// <param name="progress">Receives cumulative blocks-pinned updates.</param>
+        /// <param name="cancel">Cancellation token.</param>
+        /// <returns>Pinned CIDs on completion.</returns>
+        Task<IEnumerable<Cid>> AddAsync(string path, PinAddOptions options, IProgress<BlocksPinnedProgress> progress, CancellationToken cancel = default);
 
         /// <summary>
         ///   List all the objects pinned to local storage.
         /// </summary>
         /// <param name="cancel">
         ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
         /// </param>
-        /// <returns>
-        ///   A task that represents the asynchronous operation. The task's value
-        ///   is a sequence of <see cref="Cid"/>.
-        /// </returns>
-        Task<IEnumerable<Cid>> ListAsync(CancellationToken cancel = default);
+        /// <returns>An async sequence of <see cref="PinListItem"/>.</returns>
+        IAsyncEnumerable<PinListItem> ListAsync(CancellationToken cancel = default);
 
         /// <summary>
         ///   List all the objects pinned to local storage.
@@ -51,15 +60,24 @@ public interface IPinApi
         /// <param name="cancel">
         ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
         /// </param>
-        /// <returns>
-        ///   A task that represents the asynchronous operation. The task's value
-        ///   is a sequence of <see cref="Cid"/>.
-        /// </returns>
-        Task<IEnumerable<Cid>> ListAsync(PinType type, CancellationToken cancel = default);
+        /// <returns>An async sequence of <see cref="PinListItem"/>.</returns>
+        IAsyncEnumerable<PinListItem> ListAsync(PinType type, CancellationToken cancel = default);
+
+        /// <summary>
+        ///   List pinned objects with advanced options.
+        /// </summary>
+        /// <param name="options">List options (type filter, names, stream, etc.).</param>
+        /// <param name="cancel">Cancellation token.</param>
+        /// <returns>An async sequence of <see cref="PinListItem"/>.</returns>
+        IAsyncEnumerable<PinListItem> ListAsync(PinListOptions options, CancellationToken cancel = default);
 
         /// <summary>
         ///   Unpin an object.
         /// </summary>
+        /// <remarks>
+        ///   Unpinning does not delete the object's blocks; they become eligible for garbage
+        ///   collection and are removed only when GC runs on the node.
+        /// </remarks>
         /// <param name="id">
         ///   The CID of the object.
         /// </param>
@@ -75,5 +93,7 @@ public interface IPinApi
         ///   is a sequence of <see cref="Cid"/> that were unpinned.
         /// </returns>
         Task<IEnumerable<Cid>> RemoveAsync(Cid id, bool recursive = true, CancellationToken cancel = default);
+
+
     }
 }

src/CoreApi/PinAddOptions.cs

@@ -0,0 +1,20 @@
+using System.Collections.Generic;
+
+namespace Ipfs.CoreApi;
+
+/// <summary>
+///   Options for pin add.
+/// </summary>
+public record PinAddOptions
+{
+    /// <summary>
+    ///   Optional name for created pin(s).
+    /// </summary>
+    public string? Name { get; set; }
+
+    /// <summary>
+    ///   True to recursively pin links of the object; otherwise, false to only pin the specified object.
+    ///   Default is true.
+    /// </summary>
+    public bool Recursive { get; set; } = true;
+}

src/CoreApi/PinListItem.cs

@@ -0,0 +1,23 @@
+namespace Ipfs.CoreApi;
+
+/// <summary>
+///   A unified representation of a pin list entry that works for both
+///   streaming and non-streaming list responses.
+/// </summary>
+public record PinListItem
+{
+    /// <summary>
+    ///   The CID of the pinned object.
+    /// </summary>
+    public Ipfs.Cid Cid { get; init; } = null!;
+
+    /// <summary>
+    ///   The pin type (direct, indirect, recursive).
+    /// </summary>
+    public PinType Type { get; init; }
+
+    /// <summary>
+    ///   Optional pin name (present when names are requested and set).
+    /// </summary>
+    public string? Name { get; init; }
+}

src/CoreApi/PinListOptions.cs

@@ -0,0 +1,34 @@
+namespace Ipfs.CoreApi;
+
+/// <summary>
+///   Options for pin list.
+/// </summary>
+public record PinListOptions
+{
+    /// <summary>
+    ///   The type of pinned keys to list. Can be "direct", "indirect", "recursive", or "all".
+    ///   Default is "all".
+    /// </summary>
+    public PinType Type { get; set; } = PinType.All;
+
+    /// <summary>
+    ///   Output only the CIDs of pins.
+    /// </summary>
+    public bool Quiet { get; set; }
+
+    /// <summary>
+    ///   Limit returned pins to ones with names that contain the value provided (case-sensitive, partial match).
+    ///   Implies Names = true.
+    /// </summary>
+    public string? Name { get; set; }
+
+    /// <summary>
+    ///   Enable streaming of pins as they are discovered.
+    /// </summary>
+    public bool Stream { get; set; }
+
+    /// <summary>
+    ///   Include pin names in the output (slower, disabled by default).
+    /// </summary>
+    public bool Names { get; set; }
+}