feat(api): manual updates (#61)

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-cd6a05ae99d2a050577fa0e729e6ae89b4eacd78f61366a77269398368f8a877.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-d6a243325df36817d495ce6dd54f80766b77a97e1ca2f6d371c0a68b7d070e0f.yml

src/gitpod/resources/events.py

@@ -62,8 +62,32 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> SyncEntriesPage[EventListResponse]:
         """
-        ListAuditLogs retrieves a paginated list of audit logs for the specified
-        organization
+        Lists audit logs with filtering and pagination options.
+
+        Use this method to:
+
+        - View audit history
+        - Track user actions
+        - Monitor system changes
+
+        ### Examples
+
+        - List all logs:
+
+          ```yaml
+          pagination:
+            pageSize: 20
+          ```
+
+        - Filter by actor:
+
+          ```yaml
+          filter:
+            actorIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"]
+            actorPrincipals: ["PRINCIPAL_USER"]
+          pagination:
+            pageSize: 20
+          ```
 
         Args:
           pagination: pagination contains the pagination options for listing environments
@@ -116,7 +140,23 @@ def watch(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> JSONLDecoder[EventWatchResponse]:
         """
-        WatchEvents streams all requests events to the client
+        Streams events for all projects, runners, environments, tasks, and services
+        based on the specified scope.
+
+        Use this method to:
+
+        - Monitor resource changes in real-time
+        - Track system events
+        - Receive notifications
+
+        The scope parameter determines which events to watch:
+
+        - Organization scope (default): Watch all organization-wide events including
+          projects, runners and environments. Task and service events are not included.
+          Use by setting organization=true or omitting the scope.
+        - Environment scope: Watch events for a specific environment, including its
+          tasks, task executions, and services. Use by setting environment_id to the
+          UUID of the environment to watch.
 
         Args:
           environment_id: Environment scope produces events for the environment itself, all tasks, task
@@ -187,8 +227,32 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> AsyncPaginator[EventListResponse, AsyncEntriesPage[EventListResponse]]:
         """
-        ListAuditLogs retrieves a paginated list of audit logs for the specified
-        organization
+        Lists audit logs with filtering and pagination options.
+
+        Use this method to:
+
+        - View audit history
+        - Track user actions
+        - Monitor system changes
+
+        ### Examples
+
+        - List all logs:
+
+          ```yaml
+          pagination:
+            pageSize: 20
+          ```
+
+        - Filter by actor:
+
+          ```yaml
+          filter:
+            actorIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"]
+            actorPrincipals: ["PRINCIPAL_USER"]
+          pagination:
+            pageSize: 20
+          ```
 
         Args:
           pagination: pagination contains the pagination options for listing environments
@@ -241,7 +305,23 @@ async def watch(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> AsyncJSONLDecoder[EventWatchResponse]:
         """
-        WatchEvents streams all requests events to the client
+        Streams events for all projects, runners, environments, tasks, and services
+        based on the specified scope.
+
+        Use this method to:
+
+        - Monitor resource changes in real-time
+        - Track system events
+        - Receive notifications
+
+        The scope parameter determines which events to watch:
+
+        - Organization scope (default): Watch all organization-wide events including
+          projects, runners and environments. Task and service events are not included.
+          Use by setting organization=true or omitting the scope.
+        - Environment scope: Watch events for a specific environment, including its
+          tasks, task executions, and services. Use by setting environment_id to the
+          UUID of the environment to watch.
 
         Args:
           environment_id: Environment scope produces events for the environment itself, all tasks, task

src/gitpod/resources/groups.py

@@ -56,7 +56,35 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> SyncGroupsPage[Group]:
         """
-        ListGroups lists groups
+        Lists groups with optional pagination.
+
+        Use this method to:
+
+        - View all groups
+        - Check group memberships
+        - Monitor group configurations
+        - Audit group access
+
+        ### Examples
+
+        - List all groups:
+
+          Shows all groups with pagination.
+
+          ```yaml
+          pagination:
+            pageSize: 20
+          ```
+
+        - List with custom page size:
+
+          Shows groups with specified page size.
+
+          ```yaml
+          pagination:
+            pageSize: 50
+            token: "next-page-token-from-previous-response"
+          ```
 
         Args:
           pagination: pagination contains the pagination options for listing groups
@@ -125,7 +153,35 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> AsyncPaginator[Group, AsyncGroupsPage[Group]]:
         """
-        ListGroups lists groups
+        Lists groups with optional pagination.
+
+        Use this method to:
+
+        - View all groups
+        - Check group memberships
+        - Monitor group configurations
+        - Audit group access
+
+        ### Examples
+
+        - List all groups:
+
+          Shows all groups with pagination.
+
+          ```yaml
+          pagination:
+            pageSize: 20
+          ```
+
+        - List with custom page size:
+
+          Shows groups with specified page size.
+
+          ```yaml
+          pagination:
+            pageSize: 50
+            token: "next-page-token-from-previous-response"
+          ```
 
         Args:
           pagination: pagination contains the pagination options for listing groups