Merge pull request #109 from smar-brian-keare/bkeare/workspaces_folders

Deprecate and replace workspace and folder endpoints

Author: smar-tim-hodges

CHANGELOG.md

@@ -5,11 +5,25 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
-## [5.1.0] - 2025-08-12
+## [5.1.0] - 2025-08-25
 ### Added
 - Add support for token-based pagination in WorkspaceResources.ListWorkspaces()
 - New TokenPaginationParameters class to support paginationType, lastKey and maxItems parameters
 - New TokenPaginatedResult<T> class for token-based pagination responses with data and lastKey properties
+- GetWorkspaceChildren endpoint with support for token-based pagination
+- GetWorkspaceMetadata endpoint with support for numericDates and accessApiLevel parameters
+- GetFolderChildren endpoint with support for token-based pagination
+- GetFolderMetadata endpoint with support for numericDates parameter
+
+### Changed
+- Updated Folder model with CreatedAt and ModifiedAt properties supporting both DateTime and Long values
+
+### Deprecated
+- GetFolder method in FolderResources (use GetFolderChildren and GetFolderMetadata instead)
+- GetWorkspace method in WorkspaceResources (use GetWorkspaceChildren and GetWorkspaceMetadata instead)
+- ListFolders method in FolderResources (use GetFolderChildren instead)
+- ListFolders method in WorkspaceFolderResources (use GetWorkspaceChildren instead)
+- HomeFolderResources interface and all its methods (See the API docs article on [migrating off the Sheets folder](https://developers.smartsheet.com/api/smartsheet/guides/updating-code/migrate-from-using-the-sheets-folder))
 
 ## [3.0.0] - 2022-12-07
 ### Updated
@@ -36,16 +50,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - [Unable to Search Sheet Summary #117](https://github.com/smartsheet-platform/smartsheet-csharp-sdk/issues/117)
 
 ## [2.93.0] - 2020-03-12
-### Added 
+### Added
 - Webhooks for columns support
 
-### Fixed 
+### Fixed
 - [Json deserialization error #113](https://github.com/smartsheet-platform/smartsheet-csharp-sdk/issues/113)
 
 ### Changed
-- disable Newtonsoft default configuration of deserializing strings that "look like" dates into C# DateTime objects, 
-see [README](https://github.com/smartsheet-platform/smartsheet-csharp-sdk/blob/master/README.md) for details on how 
-to opt-out of this change if required.  
+- disable Newtonsoft default configuration of deserializing strings that "look like" dates into C# DateTime objects,
+see [README](https://github.com/smartsheet-platform/smartsheet-csharp-sdk/blob/master/README.md) for details on how
+to opt-out of this change if required.
 
 ## [2.86.0] - 2019-11-07
 ### Added
@@ -64,7 +78,7 @@ to opt-out of this change if required.
 - continue to support level 0 widget types
 
 ## [2.77.0] - 2019-07-25
-### Added 
+### Added
 - CARD_DONE tag to column tags enumeration
 - `Description` property to Column model
 - ListUsers accepts an `includes` parameter - the only currently accepted argument value is `LAST_LOGIN`
@@ -83,7 +97,7 @@ to opt-out of this change if required.
 
 ## [2.68.2] - 2019-05-29
 ### Added
-- Support for .NET Standard 2.0. Nuget.org package contains assemblies for both .NET Framework 4.5.2 and 
+- Support for .NET Standard 2.0. Nuget.org package contains assemblies for both .NET Framework 4.5.2 and
 .NET Standard 2.0.
 
 ## [2.68.1] - 2019-05-15
@@ -127,7 +141,7 @@ to opt-out of this change if required.
 - Row sort feature
 - User profile properties (including profileImage) to UserModel
 - Scope, location, and favoriteFlag inclusion to search
-- getSheet() ifVersionAfter parameter 
+- getSheet() ifVersionAfter parameter
 - Expose Change-Agent, Assumed-User, and User-Agent on Smartsheet client
 - Bulk access to sheet version through sheetVersion inclusion
 - Missing report and sheet publish flags
@@ -138,10 +152,10 @@ to opt-out of this change if required.
 
 ### Changed
 - Implementation of objectValue to better support PredecessorList and objectValue primitives (examples of how to set and clear Predecessor list can be found in the `RowTests.cs` mock tests)
-- HttpClient interface to allow SDK users to inject HTTP headers or implement an HTTP proxy by extending 
+- HttpClient interface to allow SDK users to inject HTTP headers or implement an HTTP proxy by extending
 DefaultHttpClient (a proxy sample is provided in the Advanced Topics section of the README)
 - Removed outdated Link model and replaced all references with current Hyperlink model
-- Removed ShouldRetry and CalcBackoff interfaces and replaced with HttpClient interface methods. You can now customize 
+- Removed ShouldRetry and CalcBackoff interfaces and replaced with HttpClient interface methods. You can now customize
 shouldRetry or calcBackoff using the same method as proxy or request header injection (i.e., extend DefaultHttpClient).
 
 ### Fixed

integration-test-sdk-net80/WorkspaceResourcesTest.cs

@@ -10,7 +10,7 @@ public class WorkspaceResourcesTest
         public void TestWorkspaceResources()
         {
             SmartsheetClient smartsheet = new SmartsheetBuilder().SetMaxRetryTimeout(30000).Build();
-            
+
             long workspaceId = CreateWorkspace(smartsheet);
 
             UpdateWorkspace(smartsheet, workspaceId);
@@ -48,62 +48,62 @@ private static void ListWorkspaces(SmartsheetClient smartsheet, long workspaceId
         private static void ListWorkspacesWithTokenPagination(SmartsheetClient smartsheet, long workspaceId)
         {
             // Test token-based pagination with maxItems parameter
-            TokenPaginationParameters tokenPaging = new TokenPaginationParameters(null, 100);
+            ListWorkspacesTokenPaginationParameters tokenPaging = new ListWorkspacesTokenPaginationParameters(null, 100);
             TokenPaginatedResult<Workspace> workspaceResult = smartsheet.WorkspaceResources.ListWorkspaces(tokenPaging);
-            
+
             Assert.IsNotNull(workspaceResult);
             Assert.IsNotNull(workspaceResult.Data);
             Assert.IsTrue(workspaceResult.Data.Count > 0);
 
             // Test token-based pagination with explicit paginationType parameter
-            TokenPaginationParameters tokenPagingWithType = new TokenPaginationParameters(null, 100, "token");
+            ListWorkspacesTokenPaginationParameters tokenPagingWithType = new ListWorkspacesTokenPaginationParameters(null, 100, "token");
             TokenPaginatedResult<Workspace> workspaceResultWithType = smartsheet.WorkspaceResources.ListWorkspaces(tokenPagingWithType);
             Assert.IsNotNull(workspaceResultWithType);
             Assert.IsNotNull(workspaceResultWithType.Data);
             Assert.IsTrue(workspaceResultWithType.Data.Count > 0);
             Assert.AreEqual("token", tokenPagingWithType.PaginationType);
 
             // Test token-based pagination without parameters (should get default results)
-            TokenPaginatedResult<Workspace> workspaceResultNoPaging = smartsheet.WorkspaceResources.ListWorkspaces((TokenPaginationParameters?)null);
+            TokenPaginatedResult<Workspace> workspaceResultNoPaging = smartsheet.WorkspaceResources.ListWorkspaces((ListWorkspacesTokenPaginationParameters?)null);
             Assert.IsNotNull(workspaceResultNoPaging);
             Assert.IsNotNull(workspaceResultNoPaging.Data);
             Assert.IsTrue(workspaceResultNoPaging.Data.Count > 0);
 
             // Test lastKey functionality for token pagination
             // First page with small maxItems to ensure pagination occurs
-            TokenPaginationParameters firstPageParams = new TokenPaginationParameters(null, 100);
+            ListWorkspacesTokenPaginationParameters firstPageParams = new ListWorkspacesTokenPaginationParameters(null, 100);
             TokenPaginatedResult<Workspace> firstPageResult = smartsheet.WorkspaceResources.ListWorkspaces(firstPageParams);
-            
+
             Assert.IsNotNull(firstPageResult);
             Assert.IsNotNull(firstPageResult.Data);
             Assert.IsTrue(firstPageResult.Data.Count > 0);
-            
+
             // If there are more workspaces, there should be a lastKey for the next page
             if (firstPageResult.LastKey != null)
             {
                 // Second page using the lastKey from the first page
-                TokenPaginationParameters secondPageParams = new TokenPaginationParameters(firstPageResult.LastKey, 100);
+                ListWorkspacesTokenPaginationParameters secondPageParams = new ListWorkspacesTokenPaginationParameters(firstPageResult.LastKey, 100);
                 TokenPaginatedResult<Workspace> secondPageResult = smartsheet.WorkspaceResources.ListWorkspaces(secondPageParams);
-                
+
                 Assert.IsNotNull(secondPageResult);
                 Assert.IsNotNull(secondPageResult.Data);
-                
+
                 // Verify that the second page returns different data (if available)
                 if (secondPageResult.Data.Count > 0 && firstPageResult.Data.Count > 0)
                 {
                     // The first workspace from page 1 should be different from the first workspace from page 2
-                    Assert.AreNotEqual(firstPageResult.Data[0].Id, secondPageResult.Data[0].Id, 
+                    Assert.AreNotEqual(firstPageResult.Data[0].Id, secondPageResult.Data[0].Id,
                         "Second page should return different workspaces than first page");
                 }
             }
 
             // Test that maxItems=1 generates an error from Smartsheet API
             SmartsheetException exception = Assert.ThrowsException<SmartsheetException>(() =>
             {
-                TokenPaginationParameters invalidParams = new TokenPaginationParameters(null, 1);
+                ListWorkspacesTokenPaginationParameters invalidParams = new ListWorkspacesTokenPaginationParameters(null, 1);
                 smartsheet.WorkspaceResources.ListWorkspaces(invalidParams);
             });
-            
+
             Assert.IsNotNull(exception.Message, "Exception should have a message");
         }
 

mock-api-test-sdk-net80/FolderTests.cs

@@ -0,0 +1,196 @@
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using Smartsheet.Api;
+using Smartsheet.Api.Models;
+using System.Linq;
+
+namespace mock_api_test_sdk_net80
+{
+    [TestClass]
+    public class FolderTests
+    {
+        [TestMethod]
+        public void GetFolderChildren_NoParams()
+        {
+            SmartsheetClient ss = HelperFunctions.SetupClient("Get Folder Children - No Params");
+
+            // No params - use minimal required parameters
+            TokenPaginatedResult<object> children = ss.FolderResources.GetFolderChildren(456);
+
+            Assert.IsNotNull(children);
+            Assert.IsNotNull(children.Data);
+            Assert.AreEqual(4, children.Data.Count);
+
+            // Find specific items by ID and validate their properties using proper model classes
+            var childrenList = children.Data.ToList();
+
+            // Subfolder (id: 987)
+            var subfolder = childrenList.FirstOrDefault(c => GetItemId(c) == 987) as Folder;
+            Assert.IsNotNull(subfolder);
+            Assert.AreEqual("Subfolder", subfolder.Name);
+
+            // Task List (id: 234)
+            var taskList = childrenList.FirstOrDefault(c => GetItemId(c) == 234) as Sheet;
+            Assert.IsNotNull(taskList);
+            Assert.AreEqual("Task List", taskList.Name);
+            Assert.AreEqual(AccessLevel.EDITOR, taskList.AccessLevel);
+
+            // Project Dashboard (id: 567)
+            var projectDashboard = childrenList.FirstOrDefault(c => GetItemId(c) == 567) as Sight;
+            Assert.IsNotNull(projectDashboard);
+            Assert.AreEqual("Project Dashboard", projectDashboard.Name);
+            Assert.AreEqual(AccessLevel.EDITOR, projectDashboard.AccessLevel);
+
+            // Status Report (id: 890)
+            var statusReport = childrenList.FirstOrDefault(c => GetItemId(c) == 890) as Report;
+            Assert.IsNotNull(statusReport);
+            Assert.AreEqual("Status Report", statusReport.Name);
+            Assert.AreEqual(AccessLevel.VIEWER, statusReport.AccessLevel);
+        }
+
+        [TestMethod]
+        public void GetFolderChildren_IncludeSourceAndOwnerInfo()
+        {
+            SmartsheetClient ss = HelperFunctions.SetupClient("Get Folder Children - Include Source and OwnerInfo");
+
+            // Include source and owner info as specified in scenario title
+            TokenPaginatedResult<object> children = ss.FolderResources.GetFolderChildren(
+                456,
+                null,
+                new List<ChildrenInclusion> { ChildrenInclusion.SOURCE, ChildrenInclusion.OWNER_INFO }
+            );
+
+            Assert.IsNotNull(children);
+            Assert.IsNotNull(children.Data);
+            Assert.AreEqual(4, children.Data.Count);
+
+            // Verify specific source values for each child using proper model classes
+            foreach (var item in children.Data)
+            {
+                var itemId = GetItemId(item);
+
+                // Assert specific source values based on the expected response
+                switch (itemId)
+                {
+                    case 987: // Subfolder
+                        var subfolder = item as Folder;
+                        Assert.IsNotNull(subfolder);
+                        Assert.IsNotNull(subfolder.Source);
+                        Assert.AreEqual(444L, subfolder.Source.Id);
+                        Assert.AreEqual("folder", subfolder.Source.Type);
+                        break;
+                    case 234: // Task List
+                        var taskList = item as Sheet;
+                        Assert.IsNotNull(taskList);
+                        Assert.IsNotNull(taskList.Source);
+                        Assert.AreEqual(333L, taskList.Source.Id);
+                        Assert.AreEqual("sheet", taskList.Source.Type);
+                        // Verify owner info for sheet
+                        Assert.AreEqual("[email protected]", taskList.Owner);
+                        Assert.AreEqual(2002L, taskList.OwnerId);
+                        break;
+                    case 567: // Project Dashboard
+                        var projectDashboard = item as Sight;
+                        Assert.IsNotNull(projectDashboard);
+                        Assert.IsNotNull(projectDashboard.Source);
+                        Assert.AreEqual(222L, projectDashboard.Source.Id);
+                        Assert.AreEqual("sight", projectDashboard.Source.Type);
+                        break;
+                    case 890: // Status Report
+                        var statusReport = item as Report;
+                        Assert.IsNotNull(statusReport);
+                        Assert.IsNotNull(statusReport.Source);
+                        Assert.AreEqual(111L, statusReport.Source.Id);
+                        Assert.AreEqual("report", statusReport.Source.Type);
+                        break;
+                }
+            }
+        }
+
+        [TestMethod]
+        public void GetFolderChildren_FilterSightsAndReports()
+        {
+            SmartsheetClient ss = HelperFunctions.SetupClient("Get Folder Children - Filter Sights and Reports");
+
+            // Filter to only sights and reports as specified in scenario title
+            TokenPaginatedResult<object> children = ss.FolderResources.GetFolderChildren(
+                456,
+                new List<ChildrenResourceType> { ChildrenResourceType.REPORTS, ChildrenResourceType.SIGHTS }
+            );
+
+            Assert.IsNotNull(children);
+            Assert.IsNotNull(children.Data);
+            Assert.AreEqual(3, children.Data.Count);
+
+            // Verify the returned items using proper model classes
+            var childrenList = children.Data.ToList();
+
+            // Project Dashboard (id: 567)
+            var projectDashboard = childrenList.FirstOrDefault(c => GetItemId(c) == 567) as Sight;
+            Assert.IsNotNull(projectDashboard);
+            Assert.AreEqual("Project Dashboard", projectDashboard.Name);
+            Assert.AreEqual(AccessLevel.EDITOR, projectDashboard.AccessLevel);
+
+            // Status Report (id: 890)
+            var statusReport = childrenList.FirstOrDefault(c => GetItemId(c) == 890) as Report;
+            Assert.IsNotNull(statusReport);
+            Assert.AreEqual("Status Report", statusReport.Name);
+            Assert.AreEqual(AccessLevel.VIEWER, statusReport.AccessLevel);
+
+            // Executive Summary (id: 1567)
+            var executiveSummary = childrenList.FirstOrDefault(c => GetItemId(c) == 1567) as Sight;
+            Assert.IsNotNull(executiveSummary);
+            Assert.AreEqual("Executive Summary", executiveSummary.Name);
+            Assert.AreEqual(AccessLevel.VIEWER, executiveSummary.AccessLevel);
+
+            // Verify only sights and reports are returned (no folders or sheets)
+            Assert.IsTrue(childrenList.All(item => item is Sight || item is Report));
+        }
+
+        [TestMethod]
+        public void GetFolderMetadata_NoParams()
+        {
+            SmartsheetClient ss = HelperFunctions.SetupClient("Get Folder Metadata - No Params");
+
+            // No params - use minimal required parameters
+            Folder folder = ss.FolderResources.GetFolderMetadata(456);
+
+            Assert.IsNotNull(folder);
+            Assert.AreEqual(456, folder.Id);
+            Assert.AreEqual("Project Folder", folder.Name);
+            Assert.AreEqual("https://app.smartsheet.com/b/home?lx=*****************", folder.Permalink);
+            Assert.IsNotNull(folder.CreatedAt);
+            Assert.IsNotNull(folder.ModifiedAt);
+        }
+
+        [TestMethod]
+        public void GetFolderMetadata_IncludeSource()
+        {
+            SmartsheetClient ss = HelperFunctions.SetupClient("Get Folder Metadata - Include Source");
+
+            // Include source as specified in scenario title
+            Folder folder = ss.FolderResources.GetFolderMetadata(
+                456,
+                new List<FolderInclusion> { FolderInclusion.SOURCE }
+            );
+
+            Assert.IsNotNull(folder);
+            Assert.AreEqual(456, folder.Id);
+            Assert.AreEqual("Project Folder", folder.Name);
+            Assert.IsNotNull(folder.Source);
+            Assert.AreEqual(888, folder.Source.Id);
+            Assert.AreEqual("folder", folder.Source.Type);
+        }
+
+        /// <summary>
+        /// Helper method to get the ID from any model object
+        /// </summary>
+        private long GetItemId(object item)
+        {
+            if (item is NamedModel namedModel)
+            {
+                return namedModel.Id ?? 0;
+            }
+            return 0;
+        }
+    }
+}