release: 0.4.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.3.1"
+  ".": "0.4.0"
 }

.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-064a191bc556bcab46bb5d612c844437e1a4aef5981a4a99ab7f825a96ede4fa.yml

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.0 (2025-02-21)
+
+Full Changelog: [v0.3.1...v0.4.0](https://github.com/gitpod-io/gitpod-sdk-typescript/compare/v0.3.1...v0.4.0)
+
+### Features
+
+* add lib and examples ([#36](https://github.com/gitpod-io/gitpod-sdk-typescript/issues/36)) ([1b0851c](https://github.com/gitpod-io/gitpod-sdk-typescript/commit/1b0851cdf0944a6a784dd4cf370fa967aaf56a5f))
+* **api:** manual updates ([#33](https://github.com/gitpod-io/gitpod-sdk-typescript/issues/33)) ([6c0b9a6](https://github.com/gitpod-io/gitpod-sdk-typescript/commit/6c0b9a6c1140068f2838f8451e375813f8181eb7))
+
+
+### Bug Fixes
+
+* optimize sse chunk reading off-by-one error ([#31](https://github.com/gitpod-io/gitpod-sdk-typescript/issues/31)) ([ff08afe](https://github.com/gitpod-io/gitpod-sdk-typescript/commit/ff08afe756856c253787602bc15f85557425ba01))
+
 ## 0.3.1 (2025-02-18)
 
 Full Changelog: [v0.3.0...v0.3.1](https://github.com/gitpod-io/gitpod-sdk-typescript/compare/v0.3.0...v0.3.1)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitpod/sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "The official TypeScript library for the Gitpod API",
   "author": "Gitpod <dev-feedback@gitpod.com>",
   "types": "dist/index.d.ts",

src/internal/decoders/line.ts

@@ -147,3 +147,34 @@ function findNewlineIndex(
 
   return null;
 }
+
+export function findDoubleNewlineIndex(buffer: Uint8Array): number {
+  // This function searches the buffer for the end patterns (\r\r, \n\n, \r\n\r\n)
+  // and returns the index right after the first occurrence of any pattern,
+  // or -1 if none of the patterns are found.
+  const newline = 0x0a; // \n
+  const carriage = 0x0d; // \r
+
+  for (let i = 0; i < buffer.length - 1; i++) {
+    if (buffer[i] === newline && buffer[i + 1] === newline) {
+      // \n\n
+      return i + 2;
+    }
+    if (buffer[i] === carriage && buffer[i + 1] === carriage) {
+      // \r\r
+      return i + 2;
+    }
+    if (
+      buffer[i] === carriage &&
+      buffer[i + 1] === newline &&
+      i + 3 < buffer.length &&
+      buffer[i + 2] === carriage &&
+      buffer[i + 3] === newline
+    ) {
+      // \r\n\r\n
+      return i + 4;
+    }
+  }
+
+  return -1;
+}

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 });