diff --git a/sdk/go/api_esc_extensions.go b/sdk/go/api_esc_extensions.go index c2f7994..586f16a 100644 --- a/sdk/go/api_esc_extensions.go +++ b/sdk/go/api_esc_extensions.go @@ -10,27 +10,34 @@ import ( "gopkg.in/ghodss/yaml.v1" ) +// EscClient is a client for the ESC API. +// It wraps the raw API client and provides a more convenient interface. type EscClient struct { rawClient *RawAPIClient EscAPI *EscAPIService } -func NewAuthContext(apiKey string) context.Context { +// NewAuthContext creates a new context with the given access token. +// This context can be used to authenticate requests to the ESC API. +func NewAuthContext(accessToken string) context.Context { return context.WithValue( context.Background(), ContextAPIKeys, map[string]APIKey{ - "Authorization": {Key: apiKey, Prefix: "token"}, + "Authorization": {Key: accessToken, Prefix: "token"}, }, ) } +// NewClient creates a new ESC client with the given configuration. func NewClient(cfg *Configuration) *EscClient { client := &EscClient{rawClient: NewRawAPIClient(cfg)} client.EscAPI = client.rawClient.EscAPI return client } +// ListEnvironments lists all environments in the given organization. +// If a continuation token is provided, the list will start from that token. func (c *EscClient) ListEnvironments(ctx context.Context, org string, continuationToken *string) (*OrgEnvironments, error) { request := c.EscAPI.ListEnvironments(ctx, org) if continuationToken != nil { @@ -41,6 +48,8 @@ func (c *EscClient) ListEnvironments(ctx context.Context, org string, continuati return envs, err } +// GetEnvironment retrieves the environment with the given name in the given organization. +// The environment is returned along with the raw YAML definition. func (c *EscClient) GetEnvironment(ctx context.Context, org, envName string) (*EnvironmentDefinition, string, error) { env, resp, err := c.EscAPI.GetEnvironment(ctx, org, envName).Execute() if err != nil { @@ -55,6 +64,8 @@ func (c *EscClient) GetEnvironment(ctx context.Context, org, envName string) (*E return env, string(body), nil } +// GetEnvironmentAtVersion retrieves the environment with the given name in the given organization at the given version. +// The environment is returned along with the raw YAML definition. func (c *EscClient) GetEnvironmentAtVersion(ctx context.Context, org, envName, version string) (*EnvironmentDefinition, string, error) { env, resp, err := c.EscAPI.GetEnvironmentAtVersion(ctx, org, envName, version).Execute() if err != nil { @@ -69,16 +80,21 @@ func (c *EscClient) GetEnvironmentAtVersion(ctx context.Context, org, envName, v return env, string(body), nil } +// OpenEnvironment opens the environment with the given name in the given organization. +// The open environment is returned, which contains the ID of the opened environment session to use with ReadOpenEnvironment. func (c *EscClient) OpenEnvironment(ctx context.Context, org, envName string) (*OpenEnvironment, error) { openInfo, _, err := c.EscAPI.OpenEnvironment(ctx, org, envName).Execute() return openInfo, err } +// OpenEnvironmentAtVersion opens the environment with the given name in the given organization at the given version. +// The open environment is returned, which contains the ID of the opened environment session to use with ReadOpenEnvironment. func (c *EscClient) OpenEnvironmentAtVersion(ctx context.Context, org, envName, version string) (*OpenEnvironment, error) { openInfo, _, err := c.EscAPI.OpenEnvironmentAtVersion(ctx, org, envName, version).Execute() return openInfo, err } +// ReadOpenEnvironment reads the environment with the given open session ID and returns the config and resolved secret values. func (c *EscClient) ReadOpenEnvironment(ctx context.Context, org, envName, openEnvID string) (*Environment, map[string]any, error) { env, _, err := c.EscAPI.ReadOpenEnvironment(ctx, org, envName, openEnvID).Execute() if err != nil { @@ -100,6 +116,8 @@ func (c *EscClient) ReadOpenEnvironment(ctx context.Context, org, envName, openE return env, values, nil } +// OpenAndReadEnvironment opens and reads the environment with the given name in the given organization. +// The config and resolved secret values are returned. func (c *EscClient) OpenAndReadEnvironment(ctx context.Context, org, envName string) (*Environment, map[string]any, error) { openInfo, err := c.OpenEnvironment(ctx, org, envName) if err != nil { @@ -109,6 +127,8 @@ func (c *EscClient) OpenAndReadEnvironment(ctx context.Context, org, envName str return c.ReadOpenEnvironment(ctx, org, envName, openInfo.Id) } +// OpenAndReadEnvironmentAtVersion opens and reads the environment with the given name in the given organization at the given version. +// The config and resolved secret values are returned. func (c *EscClient) OpenAndReadEnvironmentAtVersion(ctx context.Context, org, envName, version string) (*Environment, map[string]any, error) { openInfo, err := c.OpenEnvironmentAtVersion(ctx, org, envName, version) if err != nil { @@ -118,22 +138,27 @@ func (c *EscClient) OpenAndReadEnvironmentAtVersion(ctx context.Context, org, en return c.ReadOpenEnvironment(ctx, org, envName, openInfo.Id) } +// ReadEnvironmentProperty reads the property at the given path in the environment with the given open session ID. +// The property is returned along with the resolved value. func (c *EscClient) ReadEnvironmentProperty(ctx context.Context, org, envName, openEnvID, propPath string) (*Value, any, error) { prop, _, err := c.EscAPI.ReadOpenEnvironmentProperty(ctx, org, envName, openEnvID).Property(propPath).Execute() v := mapValuesPrimitive(prop.Value) return prop, v, err } +// CreateEnvironment creates a new environment with the given name in the given organization. func (c *EscClient) CreateEnvironment(ctx context.Context, org, envName string) error { _, _, err := c.EscAPI.CreateEnvironment(ctx, org, envName).Execute() return err } +// UpdateEnvironmentYaml updates the environment with the given name in the given organization with the given YAML definition. func (c *EscClient) UpdateEnvironmentYaml(ctx context.Context, org, envName, yaml string) (*EnvironmentDiagnostics, error) { diags, _, err := c.EscAPI.UpdateEnvironmentYaml(ctx, org, envName).Body(yaml).Execute() return diags, err } +// UpdateEnvironment updates the environment with the given name in the given organization with the given definition. func (c *EscClient) UpdateEnvironment(ctx context.Context, org, envName string, env *EnvironmentDefinition) (*EnvironmentDiagnostics, error) { yaml, err := MarshalEnvironmentDefinition(env) if err != nil { @@ -144,11 +169,13 @@ func (c *EscClient) UpdateEnvironment(ctx context.Context, org, envName string, return diags, err } +// DeleteEnvironment deletes the environment with the given name in the given organization. func (c *EscClient) DeleteEnvironment(ctx context.Context, org, envName string) error { _, _, err := c.EscAPI.DeleteEnvironment(ctx, org, envName).Execute() return err } +// CheckEnvironment checks the given environment definition for errors. func (c *EscClient) CheckEnvironment(ctx context.Context, org string, env *EnvironmentDefinition) (*CheckEnvironment, error) { yaml, err := MarshalEnvironmentDefinition(env) if err != nil { @@ -158,6 +185,7 @@ func (c *EscClient) CheckEnvironment(ctx context.Context, org string, env *Envir return c.CheckEnvironmentYaml(ctx, org, yaml) } +// CheckEnvironmentYaml checks the given environment YAML definition for errors. func (c *EscClient) CheckEnvironmentYaml(ctx context.Context, org, yaml string) (*CheckEnvironment, error) { check, _, err := c.EscAPI.CheckEnvironmentYaml(ctx, org).Body(yaml).Execute() var genericOpenApiError *GenericOpenAPIError @@ -169,6 +197,7 @@ func (c *EscClient) CheckEnvironmentYaml(ctx context.Context, org, yaml string) return check, err } +// DecryptEnvironment decrypts the environment with the given name in the given organization. func (c *EscClient) DecryptEnvironment(ctx context.Context, org, envName string) (*EnvironmentDefinition, string, error) { env, resp, err := c.EscAPI.DecryptEnvironment(ctx, org, envName).Execute() @@ -180,6 +209,7 @@ func (c *EscClient) DecryptEnvironment(ctx context.Context, org, envName string) return env, string(body), err } +// ListEnvironmentRevisions lists all revisions of the environment with the given name in the given organization. func (c *EscClient) ListEnvironmentRevisions(ctx context.Context, org, envName string) ([]EnvironmentRevision, error) { request := c.EscAPI.ListEnvironmentRevisions(ctx, org, envName) @@ -187,6 +217,7 @@ func (c *EscClient) ListEnvironmentRevisions(ctx context.Context, org, envName s return revs, err } +// ListEnvironmentRevisionsPaginated lists all revisions of the environment with the given name in the given organization, with pagination support. func (c *EscClient) ListEnvironmentRevisionsPaginated(ctx context.Context, org, envName string, before, count int32) ([]EnvironmentRevision, error) { request := c.EscAPI.ListEnvironmentRevisions(ctx, org, envName).Before(before).Count(count) @@ -194,6 +225,7 @@ func (c *EscClient) ListEnvironmentRevisionsPaginated(ctx context.Context, org, return revs, err } +// ListEnvironmentRevisionTags lists all tags of the environment with the given name in the given organization. func (c *EscClient) ListEnvironmentRevisionTags(ctx context.Context, org, envName string) (*EnvironmentRevisionTags, error) { request := c.EscAPI.client.EscAPI.ListEnvironmentRevisionTags(ctx, org, envName) @@ -201,6 +233,7 @@ func (c *EscClient) ListEnvironmentRevisionTags(ctx context.Context, org, envNam return revs, err } +// ListEnvironmentRevisionTagsPaginated lists all tags of the environment with the given name in the given organization, with pagination support. func (c *EscClient) ListEnvironmentRevisionTagsPaginated(ctx context.Context, org, envName string, after string, count int32) (*EnvironmentRevisionTags, error) { request := c.EscAPI.ListEnvironmentRevisionTags(ctx, org, envName).After(after).Count(count) @@ -208,6 +241,7 @@ func (c *EscClient) ListEnvironmentRevisionTagsPaginated(ctx context.Context, or return tags, err } +// GetEnvironmentRevisionTag retrieves the tag with the given name of the environment with the given name in the given organization. func (c *EscClient) GetEnvironmentRevisionTag(ctx context.Context, org, envName, tagName string) (*EnvironmentRevisionTag, error) { request := c.EscAPI.client.EscAPI.GetEnvironmentRevisionTag(ctx, org, envName, tagName) @@ -215,6 +249,7 @@ func (c *EscClient) GetEnvironmentRevisionTag(ctx context.Context, org, envName, return revision, err } +// CreateEnvironmentRevisionTag creates a new tag with the given name for the environment with the given name in the given organization. func (c *EscClient) CreateEnvironmentRevisionTag(ctx context.Context, org, envName, tagName string, revision int32) error { update := NewUpdateEnvironmentRevisionTag(revision) request := c.EscAPI.client.EscAPI.CreateEnvironmentRevisionTag(ctx, org, envName, tagName).UpdateEnvironmentRevisionTag(*update) @@ -223,6 +258,7 @@ func (c *EscClient) CreateEnvironmentRevisionTag(ctx context.Context, org, envNa return err } +// UpdateEnvironmentRevisionTag updates the tag's revision with the given name for the environment with the given name in the given organization. func (c *EscClient) UpdateEnvironmentRevisionTag(ctx context.Context, org, envName, tagName string, revision int32) error { update := NewUpdateEnvironmentRevisionTag(revision) request := c.EscAPI.client.EscAPI.UpdateEnvironmentRevisionTag(ctx, org, envName, tagName).UpdateEnvironmentRevisionTag(*update) @@ -231,6 +267,7 @@ func (c *EscClient) UpdateEnvironmentRevisionTag(ctx context.Context, org, envNa return err } +// DeleteEnvironmentRevisionTag deletes the tag with the given name for the environment with the given name in the given organization. func (c *EscClient) DeleteEnvironmentRevisionTag(ctx context.Context, org, envName, tagName string) error { request := c.EscAPI.client.EscAPI.DeleteEnvironmentRevisionTag(ctx, org, envName, tagName) diff --git a/sdk/python/pulumi_esc_sdk/configuration.py b/sdk/python/pulumi_esc_sdk/configuration.py index 10ea427..fc69c75 100644 --- a/sdk/python/pulumi_esc_sdk/configuration.py +++ b/sdk/python/pulumi_esc_sdk/configuration.py @@ -34,15 +34,6 @@ class Configuration: """This class contains various settings of the API client. :param host: Base url. - :param api_key: Dict to store API key(s). - Each entry in the dict specifies an API key. - The dict key is the name of the security scheme in the OAS specification. - The dict value is the API key secret. - :param api_key_prefix: Dict to store API prefix (e.g. Bearer). - The dict key is the name of the security scheme in the OAS specification. - The dict value is an API key prefix when generating the auth data. - :param username: Username for HTTP basic authentication. - :param password: Password for HTTP basic authentication. :param access_token: Access token. :param server_index: Index to servers configuration. :param server_variables: Mapping with string values to replace variables in diff --git a/sdk/python/pulumi_esc_sdk/esc_client.py b/sdk/python/pulumi_esc_sdk/esc_client.py index 2bd2159..994c9f6 100644 --- a/sdk/python/pulumi_esc_sdk/esc_client.py +++ b/sdk/python/pulumi_esc_sdk/esc_client.py @@ -13,67 +13,156 @@ class EscClient: - esc_api: api.EscApi = None - """EscClient + """EscClient is a client for the ESC API. + It wraps the raw API client and provides a more convenient interface. - :param esc_api: EscApi (required) + :param configuration: API client configuration. """ + esc_api: api.EscApi = None + def __init__(self, configuration: configuration.Configuration) -> None: + """Constructor + """ self.esc_api = api.EscApi(api_client.ApiClient(configuration)) def list_environments(self, org_name: str, continuation_token: str = None) -> models.OrgEnvironments: + """List all environments in an organization. + + :param org_name: The name of the organization. + :param continuation_token: The continuation token to use for pagination. + :return: The list of environments. + """ return self.esc_api.list_environments(org_name, continuation_token) def get_environment(self, org_name: str, env_name: str) -> tuple[models.EnvironmentDefinition, StrictBytes]: + """Get an environment by name. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :return: The environment definition and the raw data. + """ response = self.esc_api.get_environment_with_http_info(org_name, env_name) return response.data, response.raw_data def get_environment_at_version( self, org_name: str, env_name: str, version: str) -> tuple[models.EnvironmentDefinition, StrictBytes]: + """Get an environment by name and version. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param version: The version of the environment. + :return: The environment definition and the raw data. + """ response = self.esc_api.get_environment_at_version_with_http_info(org_name, env_name, version) return response.data, response.raw_data - def open_environment(self, org_name: str, env_name: str) -> models.Environment: + def open_environment(self, org_name: str, env_name: str) -> models.OpenEnvironment: + """Open an environment for reading. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :return: The opened environment. + """ return self.esc_api.open_environment(org_name, env_name) - def open_environment_at_version(self, org_name: str, env_name: str, version: str) -> models.Environment: + def open_environment_at_version(self, org_name: str, env_name: str, version: str) -> models.OpenEnvironment: + """Open an environment for reading at a specific version. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param version: The version of the environment. + :return: The opened environment.""" return self.esc_api.open_environment_at_version(org_name, env_name, version) def read_open_environment( self, org_name: str, env_name: str, open_session_id: str) -> tuple[models.Environment, Mapping[str, Any], str]: + """Read an open environment and resolves config and data. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param open_session_id: The open session identifier. + :return: The environment, the values, and the raw data.""" response = self.esc_api.read_open_environment_with_http_info(org_name, env_name, open_session_id) values = convertEnvPropertiesToValues(response.data.properties) return response.data, values, response.raw_data.decode('utf-8') def open_and_read_environment(self, org_name: str, env_name: str) -> tuple[models.Environment, Mapping[str, any], str]: + """Open and read an environment and resolves config and data. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :return: The environment, the values, and the raw data. + """ openEnv = self.open_environment(org_name, env_name) return self.read_open_environment(org_name, env_name, openEnv.id) def open_and_read_environment_at_version( self, org_name: str, env_name: str, version: str) -> tuple[models.Environment, Mapping[str, any], str]: + """Open and read an environment at a specific version and resolves config and data. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param version: The version of the environment. + :return: The environment, the values, and the raw data. + """ openEnv = self.open_environment_at_version(org_name, env_name, version) return self.read_open_environment(org_name, env_name, openEnv.id) def read_open_environment_property( self, org_name: str, env_name: str, open_session_id: str, property_name: str) -> tuple[models.Value, Any]: + """Read a property from an open environment and resolves the value. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param open_session_id: The open session identifier. + :param property_name: The property name. + :return: The property value and the resolved value. + """ v = self.esc_api.read_open_environment_property(org_name, env_name, open_session_id, property_name) return v, convertPropertyToValue(v.value) def create_environment(self, org_name: str, env_name: str) -> models.Environment: + """Create an environment. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :return: The created environment.""" return self.esc_api.create_environment(org_name, env_name) def update_environment_yaml(self, org_name: str, env_name: str, yaml_body: str) -> models.EnvironmentDiagnostics: + """Update an environment using the YAML body. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param yaml_body: The YAML text. + :return: The environment diagnostics.""" return self.esc_api.update_environment_yaml(org_name, env_name, yaml_body) def update_environment(self, org_name: str, env_name: str, env: models.EnvironmentDefinition) -> models.Environment: + """Update an environment using the environment definition. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param env: The environment definition. + :return: The updated environment.""" envData = env.to_dict() yaml_body = yaml.dump(envData) return self.update_environment_yaml(org_name, env_name, yaml_body) def delete_environment(self, org_name: str, env_name: str) -> None: + """Delete an environment. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + """ self.esc_api.delete_environment(org_name, env_name) def check_environment_yaml(self, org_name: str, yaml_body: str) -> models.CheckEnvironment: + """Check an environment using the YAML body. + + :param org_name: The name of the organization. + :param yaml_body: The YAML text. + :return: The check environment result with diagnostics.""" try: response = self.esc_api.check_environment_yaml_with_http_info(org_name, yaml_body) return response.data @@ -81,10 +170,20 @@ def check_environment_yaml(self, org_name: str, yaml_body: str) -> models.CheckE return e.data def check_environment(self, org_name: str, env: models.EnvironmentDefinition) -> models.CheckEnvironment: + """Check an environment using the environment definition. + + :param org_name: The name of the organization. + :param env: The environment definition. + :return: The check environment result with diagnostics.""" yaml_body = yaml.safe_dump(env.to_dict()) return self.check_environment_yaml(org_name, yaml_body) def decrypt_environment(self, org_name: str, env_name: str) -> tuple[models.EnvironmentDefinition, str]: + """Decrypt an environment. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :return: The decrypted environment and the raw data.""" response = self.esc_api.decrypt_environment_with_http_info(org_name, env_name) return response.data, response.raw_data.decode('utf-8') @@ -95,31 +194,69 @@ def list_environment_revisions( before: StrictInt | None = None, count: StrictInt | None = None ) -> List[models.EnvironmentRevision]: + """List environment revisions, from newest to oldest. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param before: The revision before which to list. + :param count: The number of revisions to list.""" return self.esc_api.list_environment_revisions(org_name, env_name, before, count) def list_environment_revision_tags( self, org_name: str, env_name: str, - before: str | None = None, + after: str | None = None, count: StrictInt | None = None ) -> models.EnvironmentRevisionTags: - return self.esc_api.list_environment_revision_tags(org_name, env_name, before, count) + """List environment revision tags. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param after: The tag after which to list. + :param count: The number of tags to list.""" + return self.esc_api.list_environment_revision_tags(org_name, env_name, after, count) def create_environment_revision_tag( - self, org_name: str, env_name: str, tag_name: str, revision: StrictInt) -> models.EnvironmentRevisionTag: + self, org_name: str, env_name: str, tag_name: str, revision: StrictInt) -> None: + """Create an environment revision tag. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param tag_name: The name of the tag. + :param revision: The revision to tag. + """ update_tag = models.UpdateEnvironmentRevisionTag(revision=revision) return self.esc_api.create_environment_revision_tag(org_name, env_name, tag_name, update_tag) def update_environment_revision_tag( - self, org_name: str, env_name: str, tag_name: str, revision: StrictInt) -> models.EnvironmentRevisionTag: + self, org_name: str, env_name: str, tag_name: str, revision: StrictInt) -> None: + """Update an environment revision tag. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param tag_name: The name of the tag. + :param revision: The revision to tag. + """ update_tag = models.UpdateEnvironmentRevisionTag(revision=revision) return self.esc_api.update_environment_revision_tag(org_name, env_name, tag_name, update_tag) def get_environment_revision_tag(self, org_name: str, env_name: str, tag_name: str) -> models.EnvironmentRevisionTag: + """Get an environment revision tag. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param tag_name: The name of the tag. + :return: The environment revision tag.""" return self.esc_api.get_environment_revision_tag(org_name, env_name, tag_name) def delete_environment_revision_tag(self, org_name: str, env_name: str, tag_name: str) -> None: + """Delete an environment revision tag. + + :param org_name: The name of the organization. + :param env_name: The name of the environment. + :param tag_name: The name of the tag. + """ self.esc_api.delete_environment_revision_tag(org_name, env_name, tag_name) diff --git a/sdk/templates/python/configuration.mustache b/sdk/templates/python/configuration.mustache index bd5a284..853cbe4 100644 --- a/sdk/templates/python/configuration.mustache +++ b/sdk/templates/python/configuration.mustache @@ -24,15 +24,6 @@ class Configuration: """This class contains various settings of the API client. :param host: Base url. - :param api_key: Dict to store API key(s). - Each entry in the dict specifies an API key. - The dict key is the name of the security scheme in the OAS specification. - The dict value is the API key secret. - :param api_key_prefix: Dict to store API prefix (e.g. Bearer). - The dict key is the name of the security scheme in the OAS specification. - The dict value is an API key prefix when generating the auth data. - :param username: Username for HTTP basic authentication. - :param password: Password for HTTP basic authentication. :param access_token: Access token. {{#hasHttpSignatureMethods}} :param signing_info: Configuration parameters for the HTTP signature security scheme. diff --git a/sdk/typescript/esc/index.ts b/sdk/typescript/esc/index.ts index 81a65c5..1f67f69 100644 --- a/sdk/typescript/esc/index.ts +++ b/sdk/typescript/esc/index.ts @@ -61,6 +61,8 @@ type KeyValueMap = { [key: string]: string }; /** * + * EscApi is a client for the ESC API. + * It wraps the raw API client and provides a more convenient interface. * @export * @class EscApi */ @@ -72,8 +74,15 @@ export class EscApi { this.rawApi = new EscRawApi(config); } - async listEnvironments(org: string, continuationToken?: string | undefined): Promise { - const resp = await this.rawApi.listEnvironments(org, continuationToken); + /** + * listEnvironments lists the environments in an organization. + * @summary List environments + * @param {string} orgName Organization name + * @param {string} continuationToken continuation Token from previous query to fetch next page of results + * @returns {Promise} A list of environments + */ + async listEnvironments(orgName: string, continuationToken?: string): Promise { + const resp = await this.rawApi.listEnvironments(orgName, continuationToken); if (resp.status === 200) { return resp.data; } @@ -81,8 +90,15 @@ export class EscApi { throw new Error(`Failed to list environments: ${resp.statusText}`); } - async getEnvironment(org: string, name: string): Promise { - const resp = await this.rawApi.getEnvironment(org, name); + /** + * getEnvironment gets the definition of an environment. + * @summary Get environment + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @returns {Promise} The environment definition and the YAML representation + */ + async getEnvironment(orgName: string, envName: string): Promise { + const resp = await this.rawApi.getEnvironment(orgName, envName); if (resp.status === 200) { const doc = yaml.load(resp.data as string); return { @@ -94,12 +110,20 @@ export class EscApi { throw new Error(`Failed to get environment: ${resp.statusText}`); } + /** + * getEnvironmentAtVersion gets the definition of an environment at a specific version. + * @summary Get environment at version + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} version Version of the environment + * @returns {Promise} The environment definition and the YAML representation + */ async getEnvironmentAtVersion( - org: string, - name: string, + orgName: string, + envName: string, version: string, ): Promise { - const resp = await this.rawApi.getEnvironmentAtVersion(org, name, version); + const resp = await this.rawApi.getEnvironmentAtVersion(orgName, envName, version); if (resp.status === 200) { const doc = yaml.load(resp.data as string); return { @@ -111,8 +135,15 @@ export class EscApi { throw new Error(`Failed to get environment: ${resp.statusText}`); } - async openEnvironment(org: string, name: string): Promise { - const resp = await this.rawApi.openEnvironment(org, name); + /** + * openEnvironment opens an environment session + * @summary Open environment + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @returns {Promise} The open environment session information + */ + async openEnvironment(orgName: string, envName: string): Promise { + const resp = await this.rawApi.openEnvironment(orgName, envName); if (resp.status === 200) { return resp.data; } @@ -120,8 +151,20 @@ export class EscApi { throw new Error(`Failed to open environment: ${resp.statusText}`); } - async openEnvironmentAtVersion(org: string, name: string, version: string): Promise { - const resp = await this.rawApi.openEnvironmentAtVersion(org, name, version); + /** + * openEnvironmentAtVersion opens an environment session at a specific version + * @summary Open environment at version + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} version Version of the environment + * @returns {Promise} The open environment session information + */ + async openEnvironmentAtVersion( + orgName: string, + envName: string, + version: string, + ): Promise { + const resp = await this.rawApi.openEnvironmentAtVersion(orgName, envName, version); if (resp.status === 200) { return resp.data; } @@ -129,12 +172,21 @@ export class EscApi { throw new Error(`Failed to open environment: ${resp.statusText}`); } + /** + * readOpenEnvironment reads the environment properties in an open session, + * resolving configuration variables and secrets. + * @summary Read environment + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} openSessionID Open session ID + * @returns {Promise} The environment and its values + */ async readOpenEnvironment( - org: string, - name: string, + orgName: string, + envName: string, openSessionID: string, ): Promise { - const resp = await this.rawApi.readOpenEnvironment(org, name, openSessionID); + const resp = await this.rawApi.readOpenEnvironment(orgName, envName, openSessionID); if (resp.status === 200) { return { environment: resp.data, @@ -145,35 +197,62 @@ export class EscApi { throw new Error(`Failed to read environment: ${resp.statusText}`); } - async openAndReadEnvironment(org: string, name: string): Promise { - const open = await this.openEnvironment(org, name); + /** + * openAndReadEnvironment opens an environment session and reads the environment properties, + * resolving configuration variables and secrets. + * @summary Open and read environment + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @returns {Promise} The environment and its values + */ + async openAndReadEnvironment(orgName: string, envName: string): Promise { + const open = await this.openEnvironment(orgName, envName); if (open?.id) { - return await this.readOpenEnvironment(org, name, open.id); + return await this.readOpenEnvironment(orgName, envName, open.id); } throw new Error(`Failed to open and read environment: ${open}`); } + /** + * openAndReadEnvironmentAtVersion opens an environment session at a specific version and reads the environment properties, + * resolving configuration variables and secrets. + * @summary Open and read environment at version + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} version Version of the environment + * @returns {Promise} The environment and its values + */ async openAndReadEnvironmentAtVersion( - org: string, - name: string, + orgName: string, + envName: string, version: string, ): Promise { - const open = await this.openEnvironmentAtVersion(org, name, version); + const open = await this.openEnvironmentAtVersion(orgName, envName, version); if (open?.id) { - return await this.readOpenEnvironment(org, name, open.id); + return await this.readOpenEnvironment(orgName, envName, open.id); } throw new Error(`Failed to open and read environment: ${open}`); } + /** + * readOpenEnvironmentProperty reads a specific environment property in an open session, + * resolving configuration variables and secrets. + * @summary Read environment property + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} openSessionID Open session ID + * @param {string} property Property name + * @returns {Promise} The environment property and its value + */ async readOpenEnvironmentProperty( - org: string, - name: string, + orgName: string, + envName: string, openSessionID: string, property: string, ): Promise { - const resp = await this.rawApi.readOpenEnvironmentProperty(org, name, openSessionID, property); + const resp = await this.rawApi.readOpenEnvironmentProperty(orgName, envName, openSessionID, property); if (resp.status === 200) { return { property: resp.data, @@ -184,8 +263,15 @@ export class EscApi { throw new Error(`Failed to read environment property: ${resp.statusText}`); } - async createEnvironment(org: string, name: string): Promise { - const resp = await this.rawApi.createEnvironment(org, name); + /** + * createEnvironment creates a new environment. + * @summary Create environment + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @returns {Promise} A promise that resolves when the environment is created + */ + async createEnvironment(orgName: string, envName: string): Promise { + const resp = await this.rawApi.createEnvironment(orgName, envName); if (resp.status === 200) { return; } @@ -193,8 +279,20 @@ export class EscApi { throw new Error(`Failed to create environment: ${resp.statusText}`); } - async updateEnvironmentYaml(org: string, name: string, yaml: string): Promise { - const resp = await this.rawApi.updateEnvironmentYaml(org, name, yaml); + /** + * updateEnvironmentYaml updates the environment definition from a YAML string. + * @summary Update environment YAML + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} yaml YAML representation of the environment + * @returns {Promise} The environment diagnostics + */ + async updateEnvironmentYaml( + orgName: string, + envName: string, + yaml: string, + ): Promise { + const resp = await this.rawApi.updateEnvironmentYaml(orgName, envName, yaml); if (resp.status === 200) { return resp.data; } @@ -202,13 +300,21 @@ export class EscApi { throw new Error(`Failed to update environment: ${resp.statusText}`); } + /** + * updateEnvironment updates the environment definition. + * @summary Update environment + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {EnvironmentDefinition} values The environment definition + * @returns {Promise} The environment diagnostics + */ async updateEnvironment( - org: string, - name: string, + orgName: string, + envName: string, values: EnvironmentDefinition, ): Promise { const body = yaml.dump(values); - const resp = await this.rawApi.updateEnvironmentYaml(org, name, body); + const resp = await this.rawApi.updateEnvironmentYaml(orgName, envName, body); if (resp.status === 200) { return resp.data; } @@ -216,8 +322,15 @@ export class EscApi { throw new Error(`Failed to update environment: ${resp.statusText}`); } - async deleteEnvironment(org: string, name: string): Promise { - const resp = await this.rawApi.deleteEnvironment(org, name); + /** + * deleteEnvironment deletes an environment. + * @summary Delete environment + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @returns {Promise} A promise that resolves when the environment is deleted + */ + async deleteEnvironment(orgName: string, envName: string): Promise { + const resp = await this.rawApi.deleteEnvironment(orgName, envName); if (resp.status === 200) { return; } @@ -225,9 +338,16 @@ export class EscApi { throw new Error(`Failed to delete environment: ${resp.statusText}`); } - async checkEnvironmentYaml(org: string, yaml: string): Promise { + /** + * checkEnvironmentYaml checks the environment definition from a YAML string. + * @summary Check environment YAML + * @param {string} orgName Organization name + * @param {string} yaml YAML representation of the environment + * @returns {Promise} The environment diagnostics + */ + async checkEnvironmentYaml(orgName: string, yaml: string): Promise { try { - const resp = await this.rawApi.checkEnvironmentYaml(org, yaml); + const resp = await this.rawApi.checkEnvironmentYaml(orgName, yaml); if (resp.status === 200) { return resp.data; } @@ -243,13 +363,27 @@ export class EscApi { } } - async checkEnvironment(org: string, env: EnvironmentDefinition): Promise { + /** + * checkEnvironment checks the environment definition. + * @summary Check environment + * @param {string} orgName Organization name + * @param {EnvironmentDefinition} env The environment definition + * @returns {Promise} The environment diagnostics + */ + async checkEnvironment(orgName: string, env: EnvironmentDefinition): Promise { const body = yaml.dump(env); - return await this.checkEnvironmentYaml(org, body); + return await this.checkEnvironmentYaml(orgName, body); } - async decryptEnvironment(org: string, name: string): Promise { - const resp = await this.rawApi.decryptEnvironment(org, name); + /** + * decryptEnvironment decrypts the environment definition. + * @summary Decrypt environment + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @returns {Promise} The decrypted environment definition and the YAML representation + */ + async decryptEnvironment(orgName: string, envName: string): Promise { + const resp = await this.rawApi.decryptEnvironment(orgName, envName); if (resp.status === 200) { const doc = yaml.load(resp.data as string); return { @@ -261,13 +395,22 @@ export class EscApi { throw new Error(`Failed to decrypt environment: ${resp.statusText}`); } + /** + * listEnvironmentRevisions lists the environment revisions, from oldest to newest. + * @summary List environment revisions + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {number} before The revision number to start listing from + * @param {number} count The number of revisions to list + * @returns {Promise | undefined>} A list of environment revisions + */ async listEnvironmentRevisions( - org: string, - name: string, + orgName: string, + envName: string, before?: number, count?: number, ): Promise | undefined> { - const resp = await this.rawApi.listEnvironmentRevisions(org, name, before, count); + const resp = await this.rawApi.listEnvironmentRevisions(orgName, envName, before, count); if (resp.status === 200) { return resp.data; } @@ -275,13 +418,22 @@ export class EscApi { throw new Error(`Failed to list environment revisions: ${resp.statusText}`); } + /** + * listEnvironmentRevisionTags lists the environment revision tags. + * @summary List environment revision tags + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} after The tag to start listing from + * @param {number} count The number of tags to list + * @returns {Promise} A list of environment revision tags + */ async listEnvironmentRevisionTags( - org: string, - name: string, + orgName: string, + envName: string, after?: string, count?: number, ): Promise { - const resp = await this.rawApi.listEnvironmentRevisionTags(org, name, after, count); + const resp = await this.rawApi.listEnvironmentRevisionTags(orgName, envName, after, count); if (resp.status === 200) { return resp.data; } @@ -289,12 +441,20 @@ export class EscApi { throw new Error(`Failed to list environment revision tags: ${resp.statusText}`); } + /** + * getEnvironmentRevisionTag gets the environment revision tag. + * @summary Get environment revision tag + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} tag The tag name + * @returns {Promise} The environment revision tag + */ async getEnvironmentRevisionTag( - org: string, - name: string, + orgName: string, + envName: string, tag: string, ): Promise { - const resp = await this.rawApi.getEnvironmentRevisionTag(org, name, tag); + const resp = await this.rawApi.getEnvironmentRevisionTag(orgName, envName, tag); if (resp.status === 200) { return resp.data; } @@ -302,11 +462,20 @@ export class EscApi { throw new Error(`Failed to get environment revision tag: ${resp.statusText}`); } - async createEnvironmentRevisionTag(org: string, name: string, tag: string, revision: number): Promise { + /** + * createEnvironmentRevisionTag creates a new environment revision tag. + * @summary Create environment revision tag + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} tag The tag name + * @param {number} revision The revision number + * @returns {Promise} A promise that resolves when the tag is created + */ + async createEnvironmentRevisionTag(orgName: string, envName: string, tag: string, revision: number): Promise { const updateTag = { revision: revision, }; - const resp = await this.rawApi.createEnvironmentRevisionTag(org, name, tag, updateTag); + const resp = await this.rawApi.createEnvironmentRevisionTag(orgName, envName, tag, updateTag); if (resp.status === 204) { return; } @@ -314,11 +483,20 @@ export class EscApi { throw new Error(`Failed to create environment revision tag: ${resp.statusText}`); } - async updateEnvironmentRevisionTag(org: string, name: string, tag: string, revision: number): Promise { + /** + * updateEnvironmentRevisionTag updates the environment revision tag. + * @summary Update environment revision tag + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} tag The tag name + * @param {number} revision The revision number + * @returns {Promise} A promise that resolves when the tag is updated + */ + async updateEnvironmentRevisionTag(orgName: string, envName: string, tag: string, revision: number): Promise { const updateTag = { revision: revision, }; - const resp = await this.rawApi.updateEnvironmentRevisionTag(org, name, tag, updateTag); + const resp = await this.rawApi.updateEnvironmentRevisionTag(orgName, envName, tag, updateTag); if (resp.status === 204) { return; } @@ -326,8 +504,16 @@ export class EscApi { throw new Error(`Failed to update environment revision tag: ${resp.statusText}`); } - async deleteEnvironmentRevisionTag(org: string, name: string, tag: string): Promise { - const resp = await this.rawApi.deleteEnvironmentRevisionTag(org, name, tag); + /** + * deleteEnvironmentRevisionTag deletes the environment revision tag. + * @summary Delete environment revision tag + * @param {string} orgName Organization name + * @param {string} envName Environment name + * @param {string} tag The tag name + * @returns {Promise} A promise that resolves when the tag is deleted + */ + async deleteEnvironmentRevisionTag(orgName: string, envName: string, tag: string): Promise { + const resp = await this.rawApi.deleteEnvironmentRevisionTag(orgName, envName, tag); if (resp.status === 204) { return; }