diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 816df2d..2537c1f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.3.1" + ".": "0.4.0" } diff --git a/.stats.yml b/.stats.yml index f08fd6b..d0c635d 100644 --- a/.stats.yml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index b5e14b8..0cf33c5 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/package.json b/package.json index 65113ef..404019c 100644 --- a/package.json +++ b/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 ", "types": "dist/index.d.ts", diff --git a/src/internal/decoders/line.ts b/src/internal/decoders/line.ts index b684dea..0295286 100644 --- a/src/internal/decoders/line.ts +++ b/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; +} diff --git a/src/resources/events.ts b/src/resources/events.ts index 2f89ac9..927e568 100644 --- a/src/resources/events.ts +++ b/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> { return this._client diff --git a/src/resources/groups.ts b/src/resources/groups.ts index 1cfe67a..b67b15c 100644 --- a/src/resources/groups.ts +++ b/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 { const { token, pageSize, ...body } = params; diff --git a/src/resources/projects/policies.ts b/src/resources/projects/policies.ts index 31c3597..07d3d09 100644 --- a/src/resources/projects/policies.ts +++ b/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 { 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 { 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 { return this._client.post('/gitpod.v1.ProjectService/DeleteProjectPolicy', { body, ...options }); diff --git a/src/resources/projects/projects.ts b/src/resources/projects/projects.ts index c82090f..66105af 100644 --- a/src/resources/projects/projects.ts +++ b/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 { 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 { 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 { 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 { 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 { 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, diff --git a/src/resources/runners/configurations/configurations.ts b/src/resources/runners/configurations/configurations.ts index 84e4622..0213678 100644 --- a/src/resources/runners/configurations/configurations.ts +++ b/src/resources/runners/configurations/configurations.ts @@ -60,8 +60,29 @@ export class Configurations extends APIResource { scmIntegrations: ScmIntegrationsAPI.ScmIntegrations = new ScmIntegrationsAPI.ScmIntegrations(this._client); /** - * ValidateRunnerConfiguration validates a runner configuration (e.g. environment - * class, SCM integration) with the runner. + * Validates a runner configuration. + * + * Use this method to: + * + * - Check configuration validity + * - Verify integration settings + * - Validate environment classes + * + * ### Examples + * + * - Validate SCM integration: + * + * Checks if an SCM integration is valid. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * scmIntegration: + * id: "integration-id" + * scmId: "github" + * host: "github.com" + * oauthClientId: "client_id" + * oauthPlaintextClientSecret: "client_secret" + * ``` */ validate( body: ConfigurationValidateParams, diff --git a/src/resources/runners/configurations/environment-classes.ts b/src/resources/runners/configurations/environment-classes.ts index 36ac039..9e70d73 100644 --- a/src/resources/runners/configurations/environment-classes.ts +++ b/src/resources/runners/configurations/environment-classes.ts @@ -10,7 +10,30 @@ import { RequestOptions } from '../../../internal/request-options'; export class EnvironmentClasses extends APIResource { /** - * CreateEnvironmentClass creates a new environment class on a runner. + * Creates a new environment class for a runner. + * + * Use this method to: + * + * - Define compute resources + * - Configure environment settings + * - Set up runtime options + * + * ### Examples + * + * - Create environment class: + * + * Creates a new environment configuration. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * displayName: "Large Instance" + * description: "8 CPU, 16GB RAM" + * configuration: + * - key: "cpu" + * value: "8" + * - key: "memory" + * value: "16384" + * ``` */ create( body: EnvironmentClassCreateParams, @@ -23,7 +46,23 @@ export class EnvironmentClasses extends APIResource { } /** - * GetEnvironmentClass returns a single environment class configured for a runner. + * Gets details about a specific environment class. + * + * Use this method to: + * + * - View class configuration + * - Check resource settings + * - Verify availability + * + * ### Examples + * + * - Get class details: + * + * Retrieves information about a specific class. + * + * ```yaml + * environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve( body: EnvironmentClassRetrieveParams, @@ -36,7 +75,26 @@ export class EnvironmentClasses extends APIResource { } /** - * UpdateEnvironmentClass updates an existing environment class on a runner. + * Updates an environment class. + * + * Use this method to: + * + * - Modify class settings + * - Update resource limits + * - Change availability + * + * ### Examples + * + * - Update class: + * + * Changes class configuration. + * + * ```yaml + * environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * displayName: "Updated Large Instance" + * description: "16 CPU, 32GB RAM" + * enabled: true + * ``` */ update(body: EnvironmentClassUpdateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerConfigurationService/UpdateEnvironmentClass', { @@ -46,8 +104,37 @@ export class EnvironmentClasses extends APIResource { } /** - * buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE ListEnvironmentClasses returns all - * environment classes configured for a runner. + * Lists environment classes with optional filtering. + * + * Use this method to: + * + * - View available classes + * - Filter by capability + * - Check enabled status + * + * ### Examples + * + * - List all classes: + * + * Shows all environment classes. + * + * ```yaml + * pagination: + * pageSize: 20 + * ``` + * + * - Filter enabled classes: + * + * Lists only enabled environment classes. + * + * ```yaml + * filter: + * enabled: true + * pagination: + * pageSize: 20 + * ``` + * + * buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE */ list( params: EnvironmentClassListParams, diff --git a/src/resources/runners/configurations/host-authentication-tokens.ts b/src/resources/runners/configurations/host-authentication-tokens.ts index d6eb144..0b7240e 100644 --- a/src/resources/runners/configurations/host-authentication-tokens.ts +++ b/src/resources/runners/configurations/host-authentication-tokens.ts @@ -7,7 +7,29 @@ import { RequestOptions } from '../../../internal/request-options'; export class HostAuthenticationTokens extends APIResource { /** - * CreateHostAuthenticationToken + * Creates a new authentication token for accessing remote hosts. + * + * Use this method to: + * + * - Set up SCM authentication + * - Configure OAuth credentials + * - Manage PAT tokens + * + * ### Examples + * + * - Create OAuth token: + * + * Creates a new OAuth-based authentication token. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * userId: "f53d2330-3795-4c5d-a1f3-453121af9c60" + * host: "github.com" + * token: "gho_xxxxxxxxxxxx" + * source: HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH + * expiresAt: "2024-12-31T23:59:59Z" + * refreshToken: "ghr_xxxxxxxxxxxx" + * ``` */ create( body: HostAuthenticationTokenCreateParams, @@ -20,7 +42,23 @@ export class HostAuthenticationTokens extends APIResource { } /** - * GetHostAuthenticationToken + * Gets details about a specific host authentication token. + * + * Use this method to: + * + * - View token information + * - Check token expiration + * - Verify token validity + * + * ### Examples + * + * - Get token details: + * + * Retrieves information about a specific token. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve( body: HostAuthenticationTokenRetrieveParams, @@ -33,7 +71,26 @@ export class HostAuthenticationTokens extends APIResource { } /** - * UpdateHostAuthenticationToken + * Updates an existing host authentication token. + * + * Use this method to: + * + * - Refresh token values + * - Update expiration + * - Modify token settings + * + * ### Examples + * + * - Update token: + * + * Updates token value and expiration. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * token: "gho_xxxxxxxxxxxx" + * expiresAt: "2024-12-31T23:59:59Z" + * refreshToken: "ghr_xxxxxxxxxxxx" + * ``` */ update(body: HostAuthenticationTokenUpdateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerConfigurationService/UpdateHostAuthenticationToken', { @@ -43,7 +100,35 @@ export class HostAuthenticationTokens extends APIResource { } /** - * ListHostAuthenticationTokens + * Lists host authentication tokens with optional filtering. + * + * Use this method to: + * + * - View all tokens + * - Filter by runner or user + * - Monitor token status + * + * ### Examples + * + * - List all tokens: + * + * Shows all tokens with pagination. + * + * ```yaml + * pagination: + * pageSize: 20 + * ``` + * + * - Filter by runner: + * + * Lists tokens for a specific runner. + * + * ```yaml + * filter: + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * pagination: + * pageSize: 20 + * ``` */ list( params: HostAuthenticationTokenListParams, @@ -58,7 +143,23 @@ export class HostAuthenticationTokens extends APIResource { } /** - * DeleteHostAuthenticationToken + * Deletes a host authentication token. + * + * Use this method to: + * + * - Remove unused tokens + * - Revoke access + * - Clean up expired tokens + * + * ### Examples + * + * - Delete token: + * + * Permanently removes a token. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ delete(body: HostAuthenticationTokenDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerConfigurationService/DeleteHostAuthenticationToken', { diff --git a/src/resources/runners/configurations/schema.ts b/src/resources/runners/configurations/schema.ts index 58fd82d..137908c 100644 --- a/src/resources/runners/configurations/schema.ts +++ b/src/resources/runners/configurations/schema.ts @@ -6,7 +6,23 @@ import { RequestOptions } from '../../../internal/request-options'; export class Schema extends APIResource { /** - * GetRunnerConfigurationSchema retrieves the latest Runner configuration schema + * Gets the latest runner configuration schema. + * + * Use this method to: + * + * - View available settings + * - Check configuration options + * - Validate configurations + * + * ### Examples + * + * - Get schema: + * + * Retrieves configuration schema for a runner. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve(body: SchemaRetrieveParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerConfigurationService/GetRunnerConfigurationSchema', { diff --git a/src/resources/runners/configurations/scm-integrations.ts b/src/resources/runners/configurations/scm-integrations.ts index e230061..d6dcc3f 100644 --- a/src/resources/runners/configurations/scm-integrations.ts +++ b/src/resources/runners/configurations/scm-integrations.ts @@ -7,7 +7,27 @@ import { RequestOptions } from '../../../internal/request-options'; export class ScmIntegrations extends APIResource { /** - * CreateSCMIntegration creates a new SCM integration on a runner. + * Creates a new SCM integration for a runner. + * + * Use this method to: + * + * - Configure source control access + * - Set up repository integrations + * - Enable code synchronization + * + * ### Examples + * + * - Create GitHub integration: + * + * Sets up GitHub SCM integration. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * scmId: "github" + * host: "github.com" + * oauthClientId: "client_id" + * oauthPlaintextClientSecret: "client_secret" + * ``` */ create( body: ScmIntegrationCreateParams, @@ -20,7 +40,23 @@ export class ScmIntegrations extends APIResource { } /** - * GetSCMIntegration returns a single SCM integration configured for a runner. + * Gets details about a specific SCM integration. + * + * Use this method to: + * + * - View integration settings + * - Check integration status + * - Verify configuration + * + * ### Examples + * + * - Get integration details: + * + * Retrieves information about a specific integration. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve( body: ScmIntegrationRetrieveParams, @@ -30,7 +66,25 @@ export class ScmIntegrations extends APIResource { } /** - * UpdateSCMIntegration updates an existing SCM integration on a runner. + * Updates an existing SCM integration. + * + * Use this method to: + * + * - Modify integration settings + * - Update credentials + * - Change configuration + * + * ### Examples + * + * - Update integration: + * + * Updates OAuth credentials. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * oauthClientId: "new_client_id" + * oauthPlaintextClientSecret: "new_client_secret" + * ``` */ update(body: ScmIntegrationUpdateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerConfigurationService/UpdateSCMIntegration', { @@ -40,7 +94,26 @@ export class ScmIntegrations extends APIResource { } /** - * ListSCMIntegrations returns all SCM integrations configured for a runner. + * Lists SCM integrations for a runner. + * + * Use this method to: + * + * - View all integrations + * - Monitor integration status + * - Check available SCMs + * + * ### Examples + * + * - List integrations: + * + * Shows all SCM integrations. + * + * ```yaml + * filter: + * runnerIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] + * pagination: + * pageSize: 20 + * ``` */ list( params: ScmIntegrationListParams, @@ -55,7 +128,23 @@ export class ScmIntegrations extends APIResource { } /** - * DeleteSCMIntegration deletes an existing SCM integration on a runner. + * Deletes an SCM integration. + * + * Use this method to: + * + * - Remove unused integrations + * - Clean up configurations + * - Revoke SCM access + * + * ### Examples + * + * - Delete integration: + * + * Removes an SCM integration. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ delete(body: ScmIntegrationDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerConfigurationService/DeleteSCMIntegration', { diff --git a/src/resources/runners/policies.ts b/src/resources/runners/policies.ts index 5d38bb5..4b71a77 100644 --- a/src/resources/runners/policies.ts +++ b/src/resources/runners/policies.ts @@ -7,21 +7,75 @@ import { RequestOptions } from '../../internal/request-options'; export class Policies extends APIResource { /** - * CreateRunnerPolicy creates a new runner policy. + * Creates a new policy for a runner. + * + * 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 + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60" + * role: RUNNER_ROLE_ADMIN + * ``` */ create(body: PolicyCreateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerService/CreateRunnerPolicy', { body, ...options }); } /** - * UpdateRunnerPolicy an existing runner policy. + * Updates an existing runner policy. + * + * Use this method to: + * + * - Modify access levels + * - Change group roles + * - Update permissions + * + * ### Examples + * + * - Update policy role: + * + * Changes a group's access level. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60" + * role: RUNNER_ROLE_USER + * ``` */ update(body: PolicyUpdateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerService/UpdateRunnerPolicy', { body, ...options }); } /** - * ListRunnerPolicies lists runner policies. + * Lists policies for a runner. + * + * Use this method to: + * + * - View access controls + * - Check policy configurations + * - Audit permissions + * + * ### Examples + * + * - List policies: + * + * Shows all policies for a runner. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * pagination: + * pageSize: 20 + * ``` */ list( params: PolicyListParams, @@ -36,7 +90,24 @@ export class Policies extends APIResource { } /** - * DeleteRunnerPolicy deletes a runner policy. + * Deletes a runner policy. + * + * Use this method to: + * + * - Remove access controls + * - Revoke permissions + * - Clean up policies + * + * ### Examples + * + * - Delete policy: + * + * Removes a group's access policy. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60" + * ``` */ delete(body: PolicyDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerService/DeleteRunnerPolicy', { body, ...options }); diff --git a/src/resources/runners/runners.ts b/src/resources/runners/runners.ts index 05a8ff5..092e0b8e 100644 --- a/src/resources/runners/runners.ts +++ b/src/resources/runners/runners.ts @@ -35,30 +35,135 @@ export class Runners extends APIResource { policies: PoliciesAPI.Policies = new PoliciesAPI.Policies(this._client); /** - * CreateRunner creates a new runner with the server. Registrations are very - * short-lived and must be renewed every 30 seconds. Runners can be registered for - * an entire organisation or a single user. + * Creates a new runner registration with the server. Registrations are very + * short-lived and must be renewed every 30 seconds. + * + * Use this method to: + * + * - Register organization runners + * - Set up runner configurations + * - Initialize runner credentials + * - Configure auto-updates + * + * ### Examples + * + * - Create cloud runner: + * + * Creates a new runner in AWS EC2. + * + * ```yaml + * name: "Production Runner" + * provider: RUNNER_PROVIDER_AWS_EC2 + * spec: + * desiredPhase: RUNNER_PHASE_ACTIVE + * configuration: + * region: "us-west" + * releaseChannel: RUNNER_RELEASE_CHANNEL_STABLE + * autoUpdate: true + * ``` + * + * - Create local runner: + * + * Creates a new local runner on Linux. + * + * ```yaml + * name: "Local Development Runner" + * provider: RUNNER_PROVIDER_LINUX_HOST + * spec: + * desiredPhase: RUNNER_PHASE_ACTIVE + * configuration: + * releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST + * autoUpdate: true + * ``` */ create(body: RunnerCreateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerService/CreateRunner', { body, ...options }); } /** - * GetRunner returns a single runner. + * Gets details about a specific runner. + * + * Use this method to: + * + * - Check runner status + * - View runner configuration + * - Monitor runner health + * - Verify runner capabilities + * + * ### Examples + * + * - Get runner details: + * + * Retrieves information about a specific runner. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve(body: RunnerRetrieveParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerService/GetRunner', { body, ...options }); } /** - * UpdateRunner updates an environment runner. + * Updates a runner's configuration. + * + * Use this method to: + * + * - Modify runner settings + * - Update release channels + * - Change runner status + * - Configure auto-update settings + * + * ### Examples + * + * - Update configuration: + * + * Changes runner settings. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * name: "Updated Runner Name" + * spec: + * configuration: + * releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST + * autoUpdate: true + * ``` */ update(body: RunnerUpdateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerService/UpdateRunner', { body, ...options }); } /** - * ListRunners returns all runners registered in the scope. + * Lists all registered runners with optional filtering. + * + * Use this method to: + * + * - View all available runners + * - Filter by runner type + * - Monitor runner status + * - Check runner availability + * + * ### Examples + * + * - List all runners: + * + * Shows all runners with pagination. + * + * ```yaml + * pagination: + * pageSize: 20 + * ``` + * + * - Filter by provider: + * + * Lists only AWS EC2 runners. + * + * ```yaml + * filter: + * providers: ["RUNNER_PROVIDER_AWS_EC2"] + * pagination: + * pageSize: 20 + * ``` */ list(params: RunnerListParams, options?: RequestOptions): PagePromise { const { token, pageSize, ...body } = params; @@ -71,17 +176,46 @@ export class Runners extends APIResource { } /** - * DeleteRunner deletes an environment runner. + * Deletes a runner permanently. + * + * Use this method to: + * + * - Remove unused runners + * - Clean up runner registrations + * - Delete obsolete runners + * + * ### Examples + * + * - Delete runner: + * + * Permanently removes a runner. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ delete(body: RunnerDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.RunnerService/DeleteRunner', { body, ...options }); } /** - * CheckAuthenticationForHost asks a runner if the user is authenticated against a - * particular host, e.g. an SCM system. If not, this function will return a URL - * that the user should visit to authenticate, or indicate that Personal Access - * Tokens are supported. + * Checks if a user is authenticated for a specific host. + * + * Use this method to: + * + * - Verify authentication status + * - Get authentication URLs + * - Check PAT support + * + * ### Examples + * + * - Check authentication: + * + * Verifies authentication for a host. + * + * ```yaml + * host: "github.com" + * ``` */ checkAuthenticationForHost( body: RunnerCheckAuthenticationForHostParams, @@ -91,9 +225,25 @@ export class Runners extends APIResource { } /** - * CreateRunnerToken returns a token that can be used to authenticate as the - * runner. Use this call to renew an outdated token - this does not expire any - * previously issued tokens. + * Creates a new authentication token for a runner. + * + * Use this method to: + * + * - Generate runner credentials + * - Renew expired tokens + * - Set up runner authentication + * + * Note: This does not expire previously issued tokens. + * + * ### Examples + * + * - Create token: + * + * Creates a new token for runner authentication. + * + * ```yaml + * runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ createRunnerToken( body: RunnerCreateRunnerTokenParams, @@ -103,18 +253,30 @@ export class Runners extends APIResource { } /** - * ParseContextURL asks a runner to parse a context URL, and return the parsed - * result. + * Parses a context URL and returns the parsed result. + * + * Use this method to: + * + * - Validate context URLs + * - Check repository access + * - Verify branch existence + * + * Returns: + * + * - FAILED_PRECONDITION if authentication is required + * - PERMISSION_DENIED if access is not allowed + * - INVALID_ARGUMENT if URL is invalid + * - NOT_FOUND if repository/branch doesn't exist + * + * ### Examples + * + * - Parse URL: * - * This call returns + * Parses and validates a context URL. * - * - FAILED_PRECONDITION if the user requires authentication on the runner to - * access the context URL - * - PERMISSION_DENIED if the user is not allowed to access the context URL using - * the credentials they have - * - INVALID_ARGUMENT if the context URL is invalid - * - NOT_FOUND if the repository or branch indicated by the context URL does not - * exist + * ```yaml + * contextUrl: "https://github.com/org/repo/tree/main" + * ``` */ parseContextURL( body: RunnerParseContextURLParams, diff --git a/src/version.ts b/src/version.ts index 99a66ad..4e7f788 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.3.1'; // x-release-please-version +export const VERSION = '0.4.0'; // x-release-please-version diff --git a/tests/api-resources/projects/projects.test.ts b/tests/api-resources/projects/projects.test.ts index 3f8e156..1ad8e40 100644 --- a/tests/api-resources/projects/projects.test.ts +++ b/tests/api-resources/projects/projects.test.ts @@ -23,7 +23,7 @@ describe('resource projects', () => { // skipped: tests are disabled for the time being test.skip('create: required and optional params', async () => { const response = await client.projects.create({ - environmentClass: { environmentClassId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', localRunner: true }, + environmentClass: { environmentClassId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', localRunner: true }, initializer: { specs: [ { @@ -31,7 +31,7 @@ describe('resource projects', () => { git: { checkoutLocation: 'checkoutLocation', cloneTarget: 'cloneTarget', - remoteUri: 'remoteUri', + remoteUri: 'https://github.com/org/repo', targetMode: 'CLONE_TARGET_MODE_UNSPECIFIED', upstreamRemoteUri: 'upstreamRemoteUri', }, @@ -40,7 +40,7 @@ describe('resource projects', () => { }, automationsFilePath: 'automationsFilePath', devcontainerFilePath: 'devcontainerFilePath', - name: 'x', + name: 'Web Application', }); });