feat(api): add sort parameter to projects list, SortOrder/SortParam types

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 175
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-5498c80829cdba9708b7765af11a4c6668383640159e195835b768d1d0070a2c.yml
-openapi_spec_hash: 9bbcc41c34e3fcc108e19e4335fa82cd
-config_hash: e561ac157e2bab45b5c366f2cf6b526e
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-8507bc4eff2dbfe0392f2a2e18b337827935aaa2d99046653efca1c43a5f82cd.yml
+openapi_spec_hash: 8a9387a75d5d0dcaa53d01ba6f52f2c9
+config_hash: 37a21c5644cb6c8f1d592ea2ec7c66d7

api.md

@@ -555,6 +555,8 @@ from gitpod.types import (
     ProjectPhase,
     ProjectPrebuildConfiguration,
     RecommendedEditors,
+    Sort,
+    SortOrder,
     ProjectCreateResponse,
     ProjectRetrieveResponse,
     ProjectUpdateResponse,

src/gitpod/resources/projects/projects.py

@@ -38,6 +38,7 @@
 from ...pagination import SyncProjectsPage, AsyncProjectsPage
 from ..._base_client import AsyncPaginator, make_request_options
 from ...types.project import Project
+from ...types.sort_param import SortParam
 from .environment_clases import (
     EnvironmentClasesResource,
     AsyncEnvironmentClasesResource,
@@ -364,6 +365,7 @@ def list(
         page_size: int | Omit = omit,
         filter: project_list_params.Filter | Omit = omit,
         pagination: project_list_params.Pagination | Omit = omit,
+        sort: SortParam | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -394,6 +396,15 @@ def list(
         Args:
           pagination: pagination contains the pagination options for listing organizations
 
+          sort: sort specifies the order of results. Defaults to popularity descending.
+
+              Supported fields:
+
+              - "id": Sort by project ID (UUID v7, effectively creation order). Produces a
+                stable, deterministic result set suitable for consistent pagination.
+              - "popularity": Sort by popularity — a precomputed score based on recent
+                environment creation activity. Updated periodically by a background job.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -409,6 +420,7 @@ def list(
                 {
                     "filter": filter,
                     "pagination": pagination,
+                    "sort": sort,
                 },
                 project_list_params.ProjectListParams,
             ),
@@ -1008,6 +1020,7 @@ def list(
         page_size: int | Omit = omit,
         filter: project_list_params.Filter | Omit = omit,
         pagination: project_list_params.Pagination | Omit = omit,
+        sort: SortParam | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -1038,6 +1051,15 @@ def list(
         Args:
           pagination: pagination contains the pagination options for listing organizations
 
+          sort: sort specifies the order of results. Defaults to popularity descending.
+
+              Supported fields:
+
+              - "id": Sort by project ID (UUID v7, effectively creation order). Produces a
+                stable, deterministic result set suitable for consistent pagination.
+              - "popularity": Sort by popularity — a precomputed score based on recent
+                environment creation activity. Updated periodically by a background job.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -1053,6 +1075,7 @@ def list(
                 {
                     "filter": filter,
                     "pagination": pagination,
+                    "sort": sort,
                 },
                 project_list_params.ProjectListParams,
             ),

src/gitpod/types/__init__.py

@@ -42,6 +42,8 @@
 from .prebuild import Prebuild as Prebuild
 from .log_level import LogLevel as LogLevel
 from .agent_mode import AgentMode as AgentMode
+from .sort_order import SortOrder as SortOrder
+from .sort_param import SortParam as SortParam
 from .veto_param import VetoParam as VetoParam
 from .environment import Environment as Environment
 from .error_level import ErrorLevel as ErrorLevel

src/gitpod/types/organization_list_members_params.py

@@ -7,6 +7,7 @@
 
 from .._types import SequenceNotStr
 from .._utils import PropertyInfo
+from .sort_order import SortOrder
 from .shared.user_status import UserStatus
 from .shared.organization_role import OrganizationRole
 
@@ -83,4 +84,4 @@ class Sort(TypedDict, total=False):
 
     field: Literal["SORT_FIELD_UNSPECIFIED", "SORT_FIELD_NAME", "SORT_FIELD_DATE_JOINED"]
 
-    order: Literal["SORT_ORDER_UNSPECIFIED", "SORT_ORDER_ASC", "SORT_ORDER_DESC"]
+    order: SortOrder

src/gitpod/types/project_list_params.py

@@ -7,6 +7,7 @@
 
 from .._types import SequenceNotStr
 from .._utils import PropertyInfo
+from .sort_param import SortParam
 from .runner_kind import RunnerKind
 
 __all__ = ["ProjectListParams", "Filter", "Pagination"]
@@ -22,6 +23,17 @@ class ProjectListParams(TypedDict, total=False):
     pagination: Pagination
     """pagination contains the pagination options for listing organizations"""
 
+    sort: SortParam
+    """sort specifies the order of results. Defaults to popularity descending.
+
+    Supported fields:
+
+    - "id": Sort by project ID (UUID v7, effectively creation order). Produces a
+      stable, deterministic result set suitable for consistent pagination.
+    - "popularity": Sort by popularity — a precomputed score based on recent
+      environment creation activity. Updated periodically by a background job.
+    """
+
 
 class Filter(TypedDict, total=False):
     project_ids: Annotated[SequenceNotStr[str], PropertyInfo(alias="projectIds")]

src/gitpod/types/sort_order.py

@@ -0,0 +1,7 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing_extensions import Literal, TypeAlias
+
+__all__ = ["SortOrder"]
+
+SortOrder: TypeAlias = Literal["SORT_ORDER_UNSPECIFIED", "SORT_ORDER_ASC", "SORT_ORDER_DESC"]

src/gitpod/types/sort_param.py

@@ -0,0 +1,16 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+from .sort_order import SortOrder
+
+__all__ = ["SortParam"]
+
+
+class SortParam(TypedDict, total=False):
+    field: str
+    """Field name to sort by, in camelCase."""
+
+    order: SortOrder

tests/api_resources/test_projects.py

@@ -221,6 +221,10 @@ def test_method_list_with_all_params(self, client: Gitpod) -> None:
                 "token": "token",
                 "page_size": 20,
             },
+            sort={
+                "field": "field",
+                "order": "SORT_ORDER_UNSPECIFIED",
+            },
         )
         assert_matches_type(SyncProjectsPage[Project], project, path=["response"])
 
@@ -757,6 +761,10 @@ async def test_method_list_with_all_params(self, async_client: AsyncGitpod) -> N
                 "token": "token",
                 "page_size": 20,
             },
+            sort={
+                "field": "field",
+                "order": "SORT_ORDER_UNSPECIFIED",
+            },
         )
         assert_matches_type(AsyncProjectsPage[Project], project, path=["response"])