From cc502c067e7197be837c31e47369c34c6ebf9e9a Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Tue, 18 Feb 2025 08:48:50 +0000 Subject: [PATCH] feat(api): manual updates --- .stats.yml | 2 +- src/resources/accounts.ts | 98 ++++++++- src/resources/editors.ts | 58 ++++- .../environments/automations/automations.ts | 35 ++- .../environments/automations/services.ts | 200 +++++++++++++++++- .../automations/tasks/executions.ts | 69 +++++- .../environments/automations/tasks/tasks.ts | 163 +++++++++++++- src/resources/environments/environments.ts | 2 +- src/resources/identity.ts | 67 +++++- src/resources/runners/runners.ts | 67 +++++- src/resources/secrets.ts | 118 ++++++++++- src/resources/shared.ts | 4 +- src/resources/users/pats.ts | 57 ++++- src/resources/users/users.ts | 47 +++- tests/api-resources/accounts.test.ts | 8 +- tests/api-resources/editors.test.ts | 16 +- 16 files changed, 951 insertions(+), 60 deletions(-) diff --git a/.stats.yml b/.stats.yml index df3a2f0..296014e 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-0c37e687e2a070abfe49501156af6d906ff166b6eaad779ee6c2b568515f2b7e.yml +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-f6598ab5d6827f66b642201769e92590ea32af84ebbf24b18cc32b33dee5107e.yml diff --git a/src/resources/accounts.ts b/src/resources/accounts.ts index 1b70feb..6704ddc 100644 --- a/src/resources/accounts.ts +++ b/src/resources/accounts.ts @@ -8,22 +8,81 @@ import { RequestOptions } from '../internal/request-options'; export class Accounts extends APIResource { /** - * GetAccount retrieves a single Account. + * Gets information about the currently authenticated account. + * + * Use this method to: + * + * - Retrieve account profile information + * - Check organization memberships + * - View account settings + * - Get joinable organizations + * + * ### Examples + * + * - Get account details: + * + * Retrieves information about the authenticated account. + * + * ```yaml + * {} + * ``` */ retrieve(body: AccountRetrieveParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.AccountService/GetAccount', { body, ...options }); } /** - * DeleteAccount deletes an Account. To Delete an Account, the Account must not be - * an active member of any Organization. + * Deletes an account permanently. + * + * Use this method to: + * + * - Remove unused accounts + * - Clean up test accounts + * - Complete account deletion requests + * + * The account must not be an active member of any organization. + * + * ### Examples + * + * - Delete account: + * + * Permanently removes an account. + * + * ```yaml + * accountId: "f53d2330-3795-4c5d-a1f3-453121af9c60" + * ``` */ delete(body: AccountDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.AccountService/DeleteAccount', { body, ...options }); } /** - * GetSSOLoginURL returns the URL to redirect the user to for SSO login. + * Gets the SSO login URL for a specific email domain. + * + * Use this method to: + * + * - Initiate SSO authentication + * - Get organization-specific login URLs + * - Handle SSO redirects + * + * ### Examples + * + * - Get login URL: + * + * Retrieves SSO URL for email domain. + * + * ```yaml + * email: "user@company.com" + * ``` + * + * - Get URL with return path: + * + * Gets SSO URL with specific return location. + * + * ```yaml + * email: "user@company.com" + * returnTo: "https://gitpod.io/workspaces" + * ``` */ getSSOLoginURL( body: AccountGetSSOLoginURLParams, @@ -33,8 +92,35 @@ export class Accounts extends APIResource { } /** - * ListLoginProviders returns the list of login providers matching the provided - * filters. + * Lists available login providers with optional filtering. + * + * Use this method to: + * + * - View supported authentication methods + * - Get provider-specific login URLs + * - Filter providers by invite + * + * ### Examples + * + * - List all providers: + * + * Shows all available login providers. + * + * ```yaml + * pagination: + * pageSize: 20 + * ``` + * + * - List for specific invite: + * + * Shows providers available for an invite. + * + * ```yaml + * filter: + * inviteId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * pagination: + * pageSize: 20 + * ``` */ listLoginProviders( params: AccountListLoginProvidersParams, diff --git a/src/resources/editors.ts b/src/resources/editors.ts index ac5e5de..11232fc 100644 --- a/src/resources/editors.ts +++ b/src/resources/editors.ts @@ -7,14 +7,47 @@ import { RequestOptions } from '../internal/request-options'; export class Editors extends APIResource { /** - * GetEditor returns the editor with the given ID + * Gets details about a specific editor. + * + * Use this method to: + * + * - View editor information + * - Get editor configuration + * + * ### Examples + * + * - Get editor details: + * + * Retrieves information about a specific editor. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve(body: EditorRetrieveParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EditorService/GetEditor', { body, ...options }); } /** - * ListEditors lists all editors available to the caller + * Lists all available code editors. + * + * Use this method to: + * + * - View supported editors + * - Get editor capabilities + * - Browse editor options + * - Check editor availability + * + * ### Examples + * + * - List editors: + * + * Shows all available editors with pagination. + * + * ```yaml + * pagination: + * pageSize: 20 + * ``` */ list(params: EditorListParams, options?: RequestOptions): PagePromise { const { token, pageSize, ...body } = params; @@ -27,7 +60,26 @@ export class Editors extends APIResource { } /** - * ResolveEditorURL resolves the editor's URL for an environment + * Resolves the URL for accessing an editor in a specific environment. + * + * Use this method to: + * + * - Get editor access URLs + * - Launch editors for environments + * - Set up editor connections + * - Configure editor access + * + * ### Examples + * + * - Resolve editor URL: + * + * Gets the URL for accessing an editor in an environment. + * + * ```yaml + * editorId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" + * organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" + * ``` */ resolveURL(body: EditorResolveURLParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EditorService/ResolveEditorURL', { body, ...options }); diff --git a/src/resources/environments/automations/automations.ts b/src/resources/environments/automations/automations.ts index 61fe991..9659f33 100644 --- a/src/resources/environments/automations/automations.ts +++ b/src/resources/environments/automations/automations.ts @@ -48,7 +48,40 @@ export class Automations extends APIResource { tasks: TasksAPI.Tasks = new TasksAPI.Tasks(this._client); /** - * UpsertAutomationsFile upserts the automations file for the given environment. + * Upserts the automations file for the given environment. + * + * Use this method to: + * + * - Configure environment automations + * - Update automation settings + * - Manage automation files + * + * ### Examples + * + * - Update automations file: + * + * Updates or creates the automations configuration. + * + * ```yaml + * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" + * automationsFile: + * services: + * web-server: + * name: "Web Server" + * description: "Development web server" + * commands: + * start: "npm run dev" + * ready: "curl -s http://localhost:3000" + * triggeredBy: + * - postDevcontainerStart + * tasks: + * build: + * name: "Build Project" + * description: "Builds the project artifacts" + * command: "npm run build" + * triggeredBy: + * - postEnvironmentStart + * ``` */ upsert(body: AutomationUpsertParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile', { diff --git a/src/resources/environments/automations/services.ts b/src/resources/environments/automations/services.ts index f45dc06..d674974 100644 --- a/src/resources/environments/automations/services.ts +++ b/src/resources/environments/automations/services.ts @@ -9,28 +9,154 @@ import { RequestOptions } from '../../../internal/request-options'; export class Services extends APIResource { /** - * CreateService + * Creates a new automation service for an environment. + * + * Use this method to: + * + * - Set up long-running services + * - Configure service triggers + * - Define service dependencies + * - Specify runtime environments + * + * ### Examples + * + * - Create basic service: + * + * Creates a simple service with start command. + * + * ```yaml + * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" + * metadata: + * reference: "web-server" + * name: "Web Server" + * description: "Runs the development web server" + * triggeredBy: + * - postDevcontainerStart: true + * spec: + * commands: + * start: "npm run dev" + * ready: "curl -s http://localhost:3000" + * ``` + * + * - Create Docker-based service: + * + * Creates a service running in a specific container. + * + * ```yaml + * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" + * metadata: + * reference: "redis" + * name: "Redis Server" + * description: "Redis cache service" + * spec: + * commands: + * start: "redis-server" + * runsOn: + * docker: + * image: "redis:7" + * ``` */ create(body: ServiceCreateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/CreateService', { body, ...options }); } /** - * GetService + * Gets details about a specific automation service. + * + * Use this method to: + * + * - Check service status + * - View service configuration + * - Monitor service health + * - Retrieve service metadata + * + * ### Examples + * + * - Get service details: + * + * Retrieves information about a specific service. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve(body: ServiceRetrieveParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/GetService', { body, ...options }); } /** - * UpdateService + * Updates an automation service configuration. + * + * Use this method to: + * + * - Modify service commands + * - Update triggers + * - Change runtime settings + * - Adjust dependencies + * + * ### Examples + * + * - Update commands: + * + * Changes service start and ready commands. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * spec: + * commands: + * start: "npm run start:dev" + * ready: "curl -s http://localhost:8080" + * ``` + * + * - Update triggers: + * + * Modifies when the service starts. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * metadata: + * triggeredBy: + * trigger: + * - postDevcontainerStart: true + * - manual: true + * ``` */ update(body: ServiceUpdateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/UpdateService', { body, ...options }); } /** - * ListServices + * Lists automation services with optional filtering. + * + * Use this method to: + * + * - View all services in an environment + * - Filter services by reference + * - Monitor service status + * + * ### Examples + * + * - List environment services: + * + * Shows all services for an environment. + * + * ```yaml + * filter: + * environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] + * pagination: + * pageSize: 20 + * ``` + * + * - Filter by reference: + * + * Lists services matching specific references. + * + * ```yaml + * filter: + * references: ["web-server", "database"] + * pagination: + * pageSize: 20 + * ``` */ list(params: ServiceListParams, options?: RequestOptions): PagePromise { const { token, pageSize, ...body } = params; @@ -42,26 +168,84 @@ export class Services extends APIResource { } /** - * DeleteService deletes a service. This call does not block until the service is + * Deletes an automation service. This call does not block until the service is * deleted. If the service is not stopped it will be stopped before deletion. + * + * Use this method to: + * + * - Remove unused services + * - Clean up service configurations + * - Stop and delete services + * + * ### Examples + * + * - Delete service: + * + * Removes a service after stopping it. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * force: false + * ``` + * + * - Force delete: + * + * Immediately removes a service. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * force: true + * ``` */ delete(body: ServiceDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/DeleteService', { body, ...options }); } /** - * StartService starts a service. This call does not block until the service is + * Starts an automation service. This call does not block until the service is * started. This call will not error if the service is already running or has been * started. + * + * Use this method to: + * + * - Start stopped services + * - Resume service operations + * - Trigger service initialization + * + * ### Examples + * + * - Start service: + * + * Starts a previously stopped service. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ start(body: ServiceStartParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/StartService', { body, ...options }); } /** - * StopService stops a service. This call does not block until the service is + * Stops an automation service. This call does not block until the service is * stopped. This call will not error if the service is already stopped or has been * stopped. + * + * Use this method to: + * + * - Pause service operations + * - Gracefully stop services + * - Prepare for updates + * + * ### Examples + * + * - Stop service: + * + * Gracefully stops a running service. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ stop(body: ServiceStopParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/StopService', { body, ...options }); @@ -71,7 +255,7 @@ export class Services extends APIResource { export type ServicesServicesPage = ServicesPage; export interface Service { - id?: string; + id: string; environmentId?: string; diff --git a/src/resources/environments/automations/tasks/executions.ts b/src/resources/environments/automations/tasks/executions.ts index 964a3bd..c1de401 100644 --- a/src/resources/environments/automations/tasks/executions.ts +++ b/src/resources/environments/automations/tasks/executions.ts @@ -9,7 +9,24 @@ import { RequestOptions } from '../../../../internal/request-options'; export class Executions extends APIResource { /** - * GetTaskExecution + * Gets details about a specific task execution. + * + * Use this method to: + * + * - Monitor execution progress + * - View execution logs + * - Check execution status + * - Debug failed executions + * + * ### Examples + * + * - Get execution details: + * + * Retrieves information about a specific task execution. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve(body: ExecutionRetrieveParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/GetTaskExecution', { @@ -19,7 +36,37 @@ export class Executions extends APIResource { } /** - * ListTaskExecutions + * Lists executions of automation tasks. + * + * Use this method to: + * + * - View task execution history + * - Monitor running tasks + * - Track task completion status + * + * ### Examples + * + * - List all executions: + * + * Shows execution history for all tasks. + * + * ```yaml + * filter: + * environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] + * pagination: + * pageSize: 20 + * ``` + * + * - Filter by phase: + * + * Lists executions in specific phases. + * + * ```yaml + * filter: + * phases: ["TASK_EXECUTION_PHASE_RUNNING", "TASK_EXECUTION_PHASE_FAILED"] + * pagination: + * pageSize: 20 + * ``` */ list( params: ExecutionListParams, @@ -34,7 +81,23 @@ export class Executions extends APIResource { } /** - * StopTaskExecution + * Stops a running task execution. + * + * Use this method to: + * + * - Cancel long-running tasks + * - Stop failed executions + * - Interrupt task processing + * + * ### Examples + * + * - Stop execution: + * + * Stops a running task execution. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ stop(body: ExecutionStopParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/StopTaskExecution', { diff --git a/src/resources/environments/automations/tasks/tasks.ts b/src/resources/environments/automations/tasks/tasks.ts index a258c34..d113e00 100644 --- a/src/resources/environments/automations/tasks/tasks.ts +++ b/src/resources/environments/automations/tasks/tasks.ts @@ -20,28 +20,145 @@ export class Tasks extends APIResource { executions: ExecutionsAPI.Executions = new ExecutionsAPI.Executions(this._client); /** - * CreateTask + * Creates a new automation task. + * + * Use this method to: + * + * - Define one-off or scheduled tasks + * - Set up build or test automation + * - Configure task dependencies + * - Specify execution environments + * + * ### Examples + * + * - Create basic task: + * + * Creates a simple build task. + * + * ```yaml + * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" + * metadata: + * reference: "build" + * name: "Build Project" + * description: "Builds the project artifacts" + * triggeredBy: + * - postEnvironmentStart: true + * spec: + * command: "npm run build" + * ``` + * + * - Create task with dependencies: + * + * Creates a task that depends on other services. + * + * ```yaml + * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" + * metadata: + * reference: "test" + * name: "Run Tests" + * description: "Runs the test suite" + * spec: + * command: "npm test" + * dependsOn: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] + * ``` */ create(body: TaskCreateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/CreateTask', { body, ...options }); } /** - * GetTask + * Gets details about a specific automation task. + * + * Use this method to: + * + * - Check task configuration + * - View task dependencies + * - Monitor task status + * + * ### Examples + * + * - Get task details: + * + * Retrieves information about a specific task. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ retrieve(body: TaskRetrieveParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/GetTask', { body, ...options }); } /** - * UpdateTask + * Updates an automation task configuration. + * + * Use this method to: + * + * - Modify task commands + * - Update task triggers + * - Change dependencies + * - Adjust execution settings + * + * ### Examples + * + * - Update command: + * + * Changes the task's command. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * spec: + * command: "npm run test:coverage" + * ``` + * + * - Update triggers: + * + * Modifies when the task runs. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * metadata: + * triggeredBy: + * trigger: + * - postEnvironmentStart: true + * ``` */ update(body: TaskUpdateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/UpdateTask', { body, ...options }); } /** - * ListTasks + * Lists automation tasks with optional filtering. + * + * Use this method to: + * + * - View all tasks in an environment + * - Filter tasks by reference + * - Monitor task status + * + * ### Examples + * + * - List environment tasks: + * + * Shows all tasks for an environment. + * + * ```yaml + * filter: + * environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] + * pagination: + * pageSize: 20 + * ``` + * + * - Filter by reference: + * + * Lists tasks matching specific references. + * + * ```yaml + * filter: + * references: ["build", "test"] + * pagination: + * pageSize: 20 + * ``` */ list(params: TaskListParams, options?: RequestOptions): PagePromise { const { token, pageSize, ...body } = params; @@ -53,15 +170,47 @@ export class Tasks extends APIResource { } /** - * DeleteTask + * Deletes an automation task. + * + * Use this method to: + * + * - Remove unused tasks + * - Clean up task configurations + * - Delete obsolete automations + * + * ### Examples + * + * - Delete task: + * + * Removes a task and its configuration. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ delete(body: TaskDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/DeleteTask', { body, ...options }); } /** - * StartTask starts a task, i.e. creates a task execution. This call does not block - * until the task is started; the task will be started asynchronously. + * Starts a task by creating a new task execution. This call does not block until + * the task is started; the task will be started asynchronously. + * + * Use this method to: + * + * - Trigger task execution + * - Run one-off tasks + * - Start scheduled tasks immediately + * + * ### Examples + * + * - Start task: + * + * Creates a new execution of a task. + * + * ```yaml + * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ start(body: TaskStartParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.EnvironmentAutomationService/StartTask', { body, ...options }); diff --git a/src/resources/environments/environments.ts b/src/resources/environments/environments.ts index 270f659..b783a6d 100644 --- a/src/resources/environments/environments.ts +++ b/src/resources/environments/environments.ts @@ -406,7 +406,7 @@ export interface Environment { * ID is a unique identifier of this environment. No other environment with the * same name must be managed by this environment manager */ - id?: string; + id: string; /** * EnvironmentMetadata is data associated with an environment that's required for diff --git a/src/resources/identity.ts b/src/resources/identity.ts index 4a30913..9bfb3fd 100644 --- a/src/resources/identity.ts +++ b/src/resources/identity.ts @@ -7,7 +7,23 @@ import { RequestOptions } from '../internal/request-options'; export class Identity extends APIResource { /** - * ExchangeToken trades an exchange token for a new access token. + * Exchanges an exchange token for a new access token. + * + * Use this method to: + * + * - Convert exchange tokens to access tokens + * - Obtain new access credentials + * - Complete token exchange flows + * + * ### Examples + * + * - Exchange token: + * + * Trades an exchange token for an access token. + * + * ```yaml + * exchangeToken: "exchange-token-value" + * ``` */ exchangeToken( body: IdentityExchangeTokenParams, @@ -17,7 +33,24 @@ export class Identity extends APIResource { } /** - * GetAuthenticatedIdentity allows to retrieve the current identity. + * Retrieves information about the currently authenticated identity. + * + * Use this method to: + * + * - Get current user information + * - Check authentication status + * - Retrieve organization context + * - Validate authentication principal + * + * ### Examples + * + * - Get current identity: + * + * Retrieves details about the authenticated user. + * + * ```yaml + * {} + * ``` */ getAuthenticatedIdentity( body: IdentityGetAuthenticatedIdentityParams, @@ -27,8 +60,34 @@ export class Identity extends APIResource { } /** - * GetIDToken returns a token that can be used to authenticate the user against the - * other services. + * Gets an ID token for authenticating with other services. + * + * Use this method to: + * + * - Obtain authentication tokens for service-to-service calls + * - Access protected resources + * - Generate scoped access tokens + * + * ### Examples + * + * - Get token for single service: + * + * Retrieves a token for authenticating with one service. + * + * ```yaml + * audience: + * - "https://api.gitpod.io" + * ``` + * + * - Get token for multiple services: + * + * Retrieves a token valid for multiple services. + * + * ```yaml + * audience: + * - "https://api.gitpod.io" + * - "https://ws.gitpod.io" + * ``` */ getIDToken( body: IdentityGetIDTokenParams, diff --git a/src/resources/runners/runners.ts b/src/resources/runners/runners.ts index b5b446f..fba3eb3 100644 --- a/src/resources/runners/runners.ts +++ b/src/resources/runners/runners.ts @@ -348,7 +348,8 @@ export interface Runner { export type RunnerCapability = | 'RUNNER_CAPABILITY_UNSPECIFIED' - | 'RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS'; + | 'RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS' + | 'RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY'; export interface RunnerConfiguration { /** @@ -579,7 +580,71 @@ export interface RunnerCheckAuthenticationForHostResponse { patSupported?: boolean; + /** + * scm_id is the unique identifier of the SCM provider + */ scmId?: string; + + /** + * scm_name is the human-readable name of the SCM provider (e.g., "GitHub", + * "GitLab") + */ + scmName?: string; + + /** + * supports_oauth2 indicates that the host supports OAuth2 authentication + */ + supportsOauth2?: RunnerCheckAuthenticationForHostResponse.SupportsOauth2; + + /** + * supports_pat indicates that the host supports Personal Access Token + * authentication + */ + supportsPat?: RunnerCheckAuthenticationForHostResponse.SupportsPat; +} + +export namespace RunnerCheckAuthenticationForHostResponse { + /** + * supports_oauth2 indicates that the host supports OAuth2 authentication + */ + export interface SupportsOauth2 { + /** + * auth_url is the URL where users can authenticate + */ + authUrl?: string; + + /** + * docs_url is the URL to the documentation explaining this authentication method + */ + docsUrl?: string; + } + + /** + * supports_pat indicates that the host supports Personal Access Token + * authentication + */ + export interface SupportsPat { + /** + * create_url is the URL where users can create a new Personal Access Token + */ + createUrl?: string; + + /** + * docs_url is the URL to the documentation explaining PAT usage for this host + */ + docsUrl?: string; + + /** + * example is an example of a Personal Access Token + */ + example?: string; + + /** + * required_scopes is the list of permissions required for the Personal Access + * Token + */ + requiredScopes?: Array; + } } export interface RunnerCreateRunnerTokenResponse { diff --git a/src/resources/secrets.ts b/src/resources/secrets.ts index 38d9729..f7473fe 100644 --- a/src/resources/secrets.ts +++ b/src/resources/secrets.ts @@ -8,14 +8,74 @@ import { RequestOptions } from '../internal/request-options'; export class Secrets extends APIResource { /** - * CreateSecret creates a new secret. + * Creates a new secret for a project. + * + * Use this method to: + * + * - Store sensitive configuration values + * - Set up environment variables + * - Configure registry authentication + * - Add file-based secrets + * + * ### Examples + * + * - Create environment variable: + * + * Creates a secret that will be available as an environment variable. + * + * ```yaml + * name: "DATABASE_URL" + * projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" + * value: "postgresql://user:pass@localhost:5432/db" + * environmentVariable: true + * ``` + * + * - Create file secret: + * + * Creates a secret that will be mounted as a file. + * + * ```yaml + * name: "SSH_KEY" + * projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" + * value: "-----BEGIN RSA PRIVATE KEY-----\n..." + * filePath: "/home/gitpod/.ssh/id_rsa" + * ``` + * + * - Create registry auth: + * + * Creates credentials for private container registry. + * + * ```yaml + * name: "DOCKER_AUTH" + * projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" + * value: "username:password" + * containerRegistryBasicAuthHost: "https://registry.example.com" + * ``` */ create(body: SecretCreateParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.SecretService/CreateSecret', { body, ...options }); } /** - * ListSecrets lists secrets. + * Lists secrets with optional filtering. + * + * Use this method to: + * + * - View all project secrets + * - Filter secrets by project + * + * ### Examples + * + * - List project secrets: + * + * Shows all secrets for a project. + * + * ```yaml + * filter: + * projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] + * pagination: + * pageSize: 20 + * ``` */ list(params: SecretListParams, options?: RequestOptions): PagePromise { const { token, pageSize, ...body } = params; @@ -28,22 +88,68 @@ export class Secrets extends APIResource { } /** - * DeleteSecret deletes a secret. + * Deletes a secret permanently. + * + * Use this method to: + * + * - Remove unused secrets + * - Clean up old credentials + * + * ### Examples + * + * - Delete secret: + * + * Permanently removes a secret. + * + * ```yaml + * secretId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ delete(body: SecretDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.SecretService/DeleteSecret', { body, ...options }); } /** - * GetSecretValue retrieves the value of a secret Only Environments can perform - * this operation, and only for secrets specified on the EnvironmentSpec. + * Gets the value of a secret. Only available to environments that are authorized + * to access the secret. + * + * Use this method to: + * + * - Retrieve secret values + * - Access credentials + * + * ### Examples + * + * - Get secret value: + * + * Retrieves the value of a specific secret. + * + * ```yaml + * secretId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ getValue(body: SecretGetValueParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.SecretService/GetSecretValue', { body, ...options }); } /** - * UpdateSecretValue updates the value of a secret. + * Updates the value of an existing secret. + * + * Use this method to: + * + * - Rotate secret values + * - Update credentials + * + * ### Examples + * + * - Update secret value: + * + * Changes the value of an existing secret. + * + * ```yaml + * secretId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * value: "new-secret-value" + * ``` */ updateValue(body: SecretUpdateValueParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.SecretService/UpdateSecretValue', { body, ...options }); diff --git a/src/resources/shared.ts b/src/resources/shared.ts index 0ef958f..c70d702 100644 --- a/src/resources/shared.ts +++ b/src/resources/shared.ts @@ -35,7 +35,7 @@ export interface EnvironmentClass { /** * id is the unique identifier of the environment class */ - id?: string; + id: string; /** * configuration describes the configuration of the environment class @@ -131,7 +131,7 @@ export interface Subject { } export interface Task { - id?: string; + id: string; /** * dependencies specifies the IDs of the automations this task depends on. diff --git a/src/resources/users/pats.ts b/src/resources/users/pats.ts index dcb49b9..46dcda4 100644 --- a/src/resources/users/pats.ts +++ b/src/resources/users/pats.ts @@ -8,7 +8,26 @@ import { RequestOptions } from '../../internal/request-options'; export class Pats extends APIResource { /** - * ListPersonalAccessTokens + * Lists personal access tokens with optional filtering. + * + * Use this method to: + * + * - View all active tokens + * - Audit token usage + * - Manage token lifecycle + * + * ### Examples + * + * - List user tokens: + * + * Shows all tokens for specific users. + * + * ```yaml + * filter: + * userIds: ["f53d2330-3795-4c5d-a1f3-453121af9c60"] + * pagination: + * pageSize: 20 + * ``` */ list( params: PatListParams, @@ -23,14 +42,46 @@ export class Pats extends APIResource { } /** - * DeletePersonalAccessToken + * Deletes a personal access token. + * + * Use this method to: + * + * - Revoke token access + * - Remove unused tokens + * - Rotate credentials + * + * ### Examples + * + * - Delete token: + * + * Permanently revokes a token. + * + * ```yaml + * personalAccessTokenId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ delete(body: PatDeleteParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.UserService/DeletePersonalAccessToken', { body, ...options }); } /** - * GetPersonalAccessToken + * Gets details about a specific personal access token. + * + * Use this method to: + * + * - View token metadata + * - Check token expiration + * - Monitor token usage + * + * ### Examples + * + * - Get token details: + * + * Retrieves information about a specific token. + * + * ```yaml + * personalAccessTokenId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" + * ``` */ get(body: PatGetParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.UserService/GetPersonalAccessToken', { body, ...options }); diff --git a/src/resources/users/users.ts b/src/resources/users/users.ts index ede6988..842292e 100644 --- a/src/resources/users/users.ts +++ b/src/resources/users/users.ts @@ -20,7 +20,24 @@ export class Users extends APIResource { pats: PatsAPI.Pats = new PatsAPI.Pats(this._client); /** - * GetAuthenticatedUser allows to retrieve the current user. + * Gets information about the currently authenticated user. + * + * Use this method to: + * + * - Get user profile information + * - Check authentication status + * - Retrieve user settings + * - Verify account details + * + * ### Examples + * + * - Get current user: + * + * Retrieves details about the authenticated user. + * + * ```yaml + * {} + * ``` */ getAuthenticatedUser( body: UserGetAuthenticatedUserParams, @@ -30,7 +47,33 @@ export class Users extends APIResource { } /** - * SetSuspended sets the suspended state of the user. + * Sets whether a user account is suspended. + * + * Use this method to: + * + * - Suspend problematic users + * - Reactivate suspended accounts + * - Manage user access + * + * ### Examples + * + * - Suspend user: + * + * Suspends a user account. + * + * ```yaml + * userId: "f53d2330-3795-4c5d-a1f3-453121af9c60" + * suspended: true + * ``` + * + * - Reactivate user: + * + * Removes suspension from a user account. + * + * ```yaml + * userId: "f53d2330-3795-4c5d-a1f3-453121af9c60" + * suspended: false + * ``` */ setSuspended(body: UserSetSuspendedParams, options?: RequestOptions): APIPromise { return this._client.post('/gitpod.v1.UserService/SetSuspended', { body, ...options }); diff --git a/tests/api-resources/accounts.test.ts b/tests/api-resources/accounts.test.ts index 932d80d..85aed19 100644 --- a/tests/api-resources/accounts.test.ts +++ b/tests/api-resources/accounts.test.ts @@ -22,7 +22,7 @@ describe('resource accounts', () => { // skipped: tests are disabled for the time being test.skip('delete: only required params', async () => { - const responsePromise = client.accounts.delete({ accountId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }); + const responsePromise = client.accounts.delete({ accountId: 'f53d2330-3795-4c5d-a1f3-453121af9c60' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -34,12 +34,12 @@ describe('resource accounts', () => { // skipped: tests are disabled for the time being test.skip('delete: required and optional params', async () => { - const response = await client.accounts.delete({ accountId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }); + const response = await client.accounts.delete({ accountId: 'f53d2330-3795-4c5d-a1f3-453121af9c60' }); }); // skipped: tests are disabled for the time being test.skip('getSSOLoginURL: only required params', async () => { - const responsePromise = client.accounts.getSSOLoginURL({ email: 'dev@stainlessapi.com' }); + const responsePromise = client.accounts.getSSOLoginURL({ email: 'user@company.com' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -52,7 +52,7 @@ describe('resource accounts', () => { // skipped: tests are disabled for the time being test.skip('getSSOLoginURL: required and optional params', async () => { const response = await client.accounts.getSSOLoginURL({ - email: 'dev@stainlessapi.com', + email: 'user@company.com', returnTo: 'https://example.com', }); }); diff --git a/tests/api-resources/editors.test.ts b/tests/api-resources/editors.test.ts index a74c114..e3e3a7c 100644 --- a/tests/api-resources/editors.test.ts +++ b/tests/api-resources/editors.test.ts @@ -10,7 +10,7 @@ const client = new Gitpod({ describe('resource editors', () => { // skipped: tests are disabled for the time being test.skip('retrieve: only required params', async () => { - const responsePromise = client.editors.retrieve({ id: 'id' }); + const responsePromise = client.editors.retrieve({ id: 'd2c94c27-3b76-4a42-b88c-95a85e392c68' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -22,7 +22,7 @@ describe('resource editors', () => { // skipped: tests are disabled for the time being test.skip('retrieve: required and optional params', async () => { - const response = await client.editors.retrieve({ id: 'id' }); + const response = await client.editors.retrieve({ id: 'd2c94c27-3b76-4a42-b88c-95a85e392c68' }); }); // skipped: tests are disabled for the time being @@ -40,9 +40,9 @@ describe('resource editors', () => { // skipped: tests are disabled for the time being test.skip('resolveURL: only required params', async () => { const responsePromise = client.editors.resolveURL({ - editorId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', - environmentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', - organizationId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', + editorId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', + environmentId: '07e03a28-65a5-4d98-b532-8ea67b188048', + organizationId: 'b0e12f6c-4c67-429d-a4a6-d9838b5da047', }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); @@ -56,9 +56,9 @@ describe('resource editors', () => { // skipped: tests are disabled for the time being test.skip('resolveURL: required and optional params', async () => { const response = await client.editors.resolveURL({ - editorId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', - environmentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', - organizationId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', + editorId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', + environmentId: '07e03a28-65a5-4d98-b532-8ea67b188048', + organizationId: 'b0e12f6c-4c67-429d-a4a6-d9838b5da047', }); }); });