feat(api): manual updates (#33)

Author: stainless-app[bot]

.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/resources/events.ts

@@ -11,8 +11,32 @@ import { JSONLDecoder } from '../internal/decoders/jsonl';
 
 export class Events extends APIResource {
   /**
-   * 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
+   *   ```
    */
   list(
     params: EventListParams,
@@ -28,7 +52,23 @@ export class Events extends APIResource {
   }
 
   /**
-   * 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.
    */
   watch(body: EventWatchParams, options?: RequestOptions): APIPromise<JSONLDecoder<EventWatchResponse>> {
     return this._client

src/resources/groups.ts

@@ -6,7 +6,35 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Groups extends APIResource {
   /**
-   * 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"
+   *   ```
    */
   list(params: GroupListParams, options?: RequestOptions): PagePromise<GroupsGroupsPage, Group> {
     const { token, pageSize, ...body } = params;

src/resources/projects/policies.ts

@@ -7,21 +7,75 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class Policies extends APIResource {
   /**
-   * CreateProjectPolicy creates a Project Policy.
+   * Creates a new policy for a project.
+   *
+   * Use this method to:
+   *
+   * - Set up access controls
+   * - Define group permissions
+   * - Configure role-based access
+   *
+   * ### Examples
+   *
+   * - Create admin policy:
+   *
+   *   Grants admin access to a group.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   role: PROJECT_ROLE_ADMIN
+   *   ```
    */
   create(body: PolicyCreateParams, options?: RequestOptions): APIPromise<PolicyCreateResponse> {
     return this._client.post('/gitpod.v1.ProjectService/CreateProjectPolicy', { body, ...options });
   }
 
   /**
-   * UpdateProjectPolicy updates a Project Policy.
+   * Updates an existing project policy.
+   *
+   * Use this method to:
+   *
+   * - Modify access levels
+   * - Change group roles
+   * - Update permissions
+   *
+   * ### Examples
+   *
+   * - Update policy role:
+   *
+   *   Changes a group's access level.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   role: PROJECT_ROLE_EDITOR
+   *   ```
    */
   update(body: PolicyUpdateParams, options?: RequestOptions): APIPromise<PolicyUpdateResponse> {
     return this._client.post('/gitpod.v1.ProjectService/UpdateProjectPolicy', { body, ...options });
   }
 
   /**
-   * ListProjectPolicies lists policies for a project.
+   * Lists policies for a project.
+   *
+   * Use this method to:
+   *
+   * - View access controls
+   * - Check policy configurations
+   * - Audit permissions
+   *
+   * ### Examples
+   *
+   * - List policies:
+   *
+   *   Shows all policies for a project.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(
     params: PolicyListParams,
@@ -36,7 +90,24 @@ export class Policies extends APIResource {
   }
 
   /**
-   * DeleteProjectPolicy deletes a Project Policy.
+   * Deletes a project policy.
+   *
+   * Use this method to:
+   *
+   * - Remove access controls
+   * - Revoke permissions
+   * - Clean up policies
+   *
+   * ### Examples
+   *
+   * - Delete policy:
+   *
+   *   Removes a group's access policy.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   ```
    */
   delete(body: PolicyDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.ProjectService/DeleteProjectPolicy', { body, ...options });

src/resources/projects/projects.ts

@@ -24,28 +24,128 @@ export class Projects extends APIResource {
   policies: PoliciesAPI.Policies = new PoliciesAPI.Policies(this._client);
 
   /**
-   * CreateProject creates a new Project.
+   * Creates a new project with specified configuration.
+   *
+   * Use this method to:
+   *
+   * - Set up development projects
+   * - Configure project environments
+   * - Define project settings
+   * - Initialize project content
+   *
+   * ### Examples
+   *
+   * - Create basic project:
+   *
+   *   Creates a project with minimal configuration.
+   *
+   *   ```yaml
+   *   name: "Web Application"
+   *   environmentClass:
+   *     environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   initializer:
+   *     specs:
+   *       - git:
+   *           remoteUri: "https://github.com/org/repo"
+   *   ```
+   *
+   * - Create project with devcontainer:
+   *
+   *   Creates a project with custom development container.
+   *
+   *   ```yaml
+   *   name: "Backend Service"
+   *   environmentClass:
+   *     environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   initializer:
+   *     specs:
+   *       - git:
+   *           remoteUri: "https://github.com/org/backend"
+   *   devcontainerFilePath: ".devcontainer/devcontainer.json"
+   *   automationsFilePath: ".gitpod/automations.yaml"
+   *   ```
    */
   create(body: ProjectCreateParams, options?: RequestOptions): APIPromise<ProjectCreateResponse> {
     return this._client.post('/gitpod.v1.ProjectService/CreateProject', { body, ...options });
   }
 
   /**
-   * GetProject retrieves a single Project.
+   * Gets details about a specific project.
+   *
+   * Use this method to:
+   *
+   * - View project configuration
+   * - Check project status
+   * - Get project metadata
+   *
+   * ### Examples
+   *
+   * - Get project details:
+   *
+   *   Retrieves information about a specific project.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   ```
    */
   retrieve(body: ProjectRetrieveParams, options?: RequestOptions): APIPromise<ProjectRetrieveResponse> {
     return this._client.post('/gitpod.v1.ProjectService/GetProject', { body, ...options });
   }
 
   /**
-   * UpdateProject updates the properties of a Project.
+   * Updates a project's configuration.
+   *
+   * Use this method to:
+   *
+   * - Modify project settings
+   * - Update environment class
+   * - Change project name
+   * - Configure initializers
+   *
+   * ### Examples
+   *
+   * - Update project name:
+   *
+   *   Changes the project's display name.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   name: "New Project Name"
+   *   ```
+   *
+   * - Update environment class:
+   *
+   *   Changes the project's environment class.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   environmentClass:
+   *     environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   update(body: ProjectUpdateParams, options?: RequestOptions): APIPromise<ProjectUpdateResponse> {
     return this._client.post('/gitpod.v1.ProjectService/UpdateProject', { body, ...options });
   }
 
   /**
-   * ListProjects lists all projects the caller has access to.
+   * Lists projects with optional filtering.
+   *
+   * Use this method to:
+   *
+   * - View all accessible projects
+   * - Browse project configurations
+   * - Monitor project status
+   *
+   * ### Examples
+   *
+   * - List projects:
+   *
+   *   Shows all projects with pagination.
+   *
+   *   ```yaml
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(params: ProjectListParams, options?: RequestOptions): PagePromise<ProjectsProjectsPage, Project> {
     const { token, pageSize, ...body } = params;
@@ -58,14 +158,47 @@ export class Projects extends APIResource {
   }
 
   /**
-   * DeleteProject deletes the specified project.
+   * Deletes a project permanently.
+   *
+   * Use this method to:
+   *
+   * - Remove unused projects
+   * - Clean up test projects
+   * - Delete obsolete configurations
+   *
+   * ### Examples
+   *
+   * - Delete project:
+   *
+   *   Permanently removes a project.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   ```
    */
   delete(body: ProjectDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.ProjectService/DeleteProject', { body, ...options });
   }
 
   /**
-   * CreateProject creates a new Project using an environment as template.
+   * Creates a new project using an existing environment as a template.
+   *
+   * Use this method to:
+   *
+   * - Clone environment configurations
+   * - Create projects from templates
+   * - Share environment setups
+   *
+   * ### Examples
+   *
+   * - Create from environment:
+   *
+   *   Creates a project based on existing environment.
+   *
+   *   ```yaml
+   *   name: "Frontend Project"
+   *   environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
+   *   ```
    */
   createFromEnvironment(
     body: ProjectCreateFromEnvironmentParams,