npm

@dynatrace-sdk/client-state
TypeScript icon, indicating that this package has built-in type declarations

1.6.0 • Public • Published

@dynatrace-sdk/client-state

npm License

Overview

Provides key-value storage for apps so that app developers can persist and get small chunks of state in the context of their app.

States can either be stored in the context of an app (= app states) or in the context of an app and user (= user app states).

  • States stored per app can be read by every user of the app.
  • States stored per app and user can only be read and updated by the user who originally set that state. Please visit the Dynatrace Developer to learn more about app states and user app states.

Installation

npm install @dynatrace-sdk/client-state

Getting help

License

This SDK is distributed under the Apache License, Version 2.0, see LICENSE for more information.

API reference

Full API reference for the latest version of the SDK is also available at the Dynatrace Developer.

stateClient

import { stateClient } from '@dynatrace-sdk/client-state';

deleteAppState

stateClient.deleteAppState(config): Promise<void>

Deletes app state

Required scope: state:app-states:delete

Parameters

Name Type Description
config.key*required string Specify the key of the state

Throws

Error Type Error Message
Unauthorized Unauthorized
Forbidden Forbidden
NotFound Not found
InternalServerError Internal server error
Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.deleteAppState({
  key: "some-key",
});

deleteAppStates

stateClient.deleteAppStates(config): Promise<void>

Delete all app states

Required scope: state:app-states:delete

Deletes all app states for an app to reset the app into a clean state.

Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.deleteAppStates();

deleteUserAppState

stateClient.deleteUserAppState(config): Promise<void>

Delete user app state

Required scope: state:user-app-states:delete

Parameters

Name Type Description
config.key*required string Specify the key of the state

Throws

Error Type Error Message
Unauthorized Unauthorized
Forbidden Forbidden
NotFound Not found
InternalServerError Internal server error
Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.deleteUserAppState({
  key: "some-key",
});

deleteUserAppStates

stateClient.deleteUserAppStates(config): Promise<void>

Delete all user app states

Required scope: state:user-app-states:delete

Deletes all user app states for the calling user and app.

Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.deleteUserAppStates();

getAppState

stateClient.getAppState(config): Promise<AppState>

Gets app state

Required scope: state:app-states:read

Parameters

Name Type Description
config.key*required string Specify the key of the state

Returns

The app state

Throws

Error Type Error Message
Unauthorized Unauthorized
Forbidden Forbidden
NotFound Not found
InternalServerError Internal server error
Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.getAppState({
  key: "some-key",
});

getAppStates

stateClient.getAppStates(config): Promise<AppStates>

List app states

Required scope: state:app-states:read

Lists app states. By default, only provides property key per state. Use add-fields parameter to include more fields and the filter parameter to narrow down the returned states.

Parameters

Name Type Description
config.addFields string Provide a comma separated list of additional properties to be included in the response.
config.filter string

The filter parameter for filtering the set of returned resources If this parameter is omitted, no filtering is applied and all states will be returned.

Filtering by string type parameters key, modificationInfo.lastModifiedBy when using one of the operators contains, starts-with and ends-with is case insensitive.

When using the operators =and !=, filtering is case sensitive.

The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response:

  • key, supported operators: =, !=, contains, starts-with, ends-with:

  • modificationInfo.lastModifiedTime, supported operators: =, !=, <, <=, >, >=

  • modificationInfo.lastModifiedBy, supported operators: =, !=, contains, starts-with, ends-with

  • validUntilTime, supported operators: =, !=, <, <=, >, >=

The following constraints apply:

  • Field names are case-sensitive.

  • Conditions can be connected via operators and and or. A single condition can be negated by not.

  • Strings must be enclosed in single quotes. e.g. key contains 'my-string'

  • Single quotes within a string must be escaped with a backslash: e.g. key starts-with 'it\'s a string'

  • Maximum nesting depth (via brackets) is 2.

  • Maximum length is 256 characters.

Examples:

  • key starts-with 'game-'

  • modificationInfo.lastModifiedTime >= '2022-07-01T00:10:05.000Z' and not (key contains 'new')

Returns

The list of app states

Throws

Error Type Error Message
Unauthorized Unauthorized
Forbidden Forbidden
InternalServerError Internal server error
Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.getAppStates();

getUserAppState

stateClient.getUserAppState(config): Promise<UserAppState>

Get user app state

Required scope: state:user-app-states:read

Parameters

Name Type Description
config.key*required string Specify the key of the state

Returns

The user app state

Throws

Error Type Error Message
Unauthorized Unauthorized
Forbidden Forbidden
NotFound Not found
InternalServerError Internal server error
Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.getUserAppState({
  key: "some-key",
});

getUserAppStates

stateClient.getUserAppStates(config): Promise<UserAppStates>

List user app states

Required scope: state:user-app-states:read

Lists user app states. By default, only provides property key per state. Use add-fields parameter to include more fields and the filter parameter to narrow down the returned states

Parameters

Name Type Description
config.addFields string Provide a comma separated list of additional properties to be included in the response.
config.filter string

The filter parameter for filtering the set of returned resources If this parameter is omitted, no filtering is applied and all states will be returned.

Filtering by string type parameters key, modificationInfo.lastModifiedBy when using one of the operators contains, starts-with and ends-with is case insensitive.

When using the operators =and !=, filtering is case sensitive.

The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response:

  • key, supported operators: =, !=, contains, starts-with, ends-with:

  • modificationInfo.lastModifiedTime, supported operators: =, !=, <, <=, >, >=

  • modificationInfo.lastModifiedBy, supported operators: =, !=, contains, starts-with, ends-with

  • validUntilTime, supported operators: =, !=, <, <=, >, >=

The following constraints apply:

  • Field names are case-sensitive.

  • Conditions can be connected via operators and and or. A single condition can be negated by not.

  • Strings must be enclosed in single quotes. e.g. key contains 'my-string'

  • Single quotes within a string must be escaped with a backslash: e.g. key starts-with 'it\'s a string'

  • Maximum nesting depth (via brackets) is 2.

  • Maximum length is 256 characters.

Examples:

  • key starts-with 'game-'

  • modificationInfo.lastModifiedTime >= '2022-07-01T00:10:05.000Z' and not (key contains 'new')

Returns

The list of user app states

Throws

Error Type Error Message
Unauthorized Unauthorized
Forbidden Forbidden
InternalServerError Internal server error
Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.getUserAppStates();

setAppState

stateClient.setAppState(config): Promise<void>

Updates app state

Required scope: state:app-states:write

Updates the cross-user app state for the given key. Be aware that other users will be able to read the value. Use the user-scoped user-app-state to only store values for the authenticated user.

Certain limits apply when updating app states.

Parameters

Name Type Description
config.body*required AppState
config.key*required string Specify the key of the state

Throws

Error Type Error Message
AppStateLimitsExceeded Exceeded size limit for combined size of app states of this app
Unauthorized Unauthorized
Forbidden Forbidden
InternalServerError Internal server error
Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.setAppState({
  key: "some-key",
  body: { value: "some-state", validUntilTime: "now+2d" },
});

setUserAppState

stateClient.setUserAppState(config): Promise<void>

Updates user app state

Required scope: state:user-app-states:write

Updates the user specific app state for the given key and calling user.

Certain limits apply when updating user app states.

Parameters

Name Type Description
config.body*required UserAppState
config.key*required string Specify the key of the state

Throws

Error Type Error Message
UserAppStateLimitsExceeded Exceeded limit for number of user app states to be stored for this user and app
Unauthorized Unauthorized
Forbidden Forbidden
InternalServerError Internal server error
Code example
import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.setUserAppState({
  key: "some-key",
  body: { value: "some-state", validUntilTime: "now+2d" },
});

Types

ApiClientError

Base error for all client SDKs. All other errors extend this class.

Name Type Description
cause any
errorType*required ErrorType
isApiClientError*required true
message*required string
name*required string
stack string
prepareStackTrace Object Optional override for formatting stack traces
stackTraceLimit*required number

ApiGatewayError

Dedicated error response class for errors thrown by API Gateway. Autogenerated SDK Clients have built-in handler for API Gateway errors that throws this error.

Name Type Description
body*required ApiGatewayErrorResponseBody
cause any
code*required number
errorType*required ErrorType
isApiClientError*required true
isApiGatewayError*required true
isClientRequestError*required true
message*required string
name*required string
response*required HttpClientResponse
retryAfterSeconds*required undefined | number
stack string
prepareStackTrace Object Optional override for formatting stack traces
stackTraceLimit*required number

AppStateLimitsExceeded

Name Type Description
body*requiredDEPRECATED ErrorResponse
causeDEPRECATED any
errorType*requiredDEPRECATED ErrorType
isApiClientError*requiredDEPRECATED true
isAppStateLimitsExceeded*requiredDEPRECATED true
isClientRequestError*requiredDEPRECATED true
isErrorResponseError*requiredDEPRECATED true
message*requiredDEPRECATED string
name*requiredDEPRECATED "AppStateLimitsExceeded"
response*requiredDEPRECATED HttpClientResponse
stackDEPRECATED string
prepareStackTraceDEPRECATED Object Optional override for formatting stack traces
stackTraceLimit*requiredDEPRECATED number

ClientRequestError

Generic error class for service errors, used to handle both expected and unexpected service-level errors.

Name Type Description
body*required DTO
cause any
errorType*required ErrorType
isApiClientError*required true
isClientRequestError*required true
message*required string
name*required string
response*required HttpClientResponse
stack string
prepareStackTrace Object Optional override for formatting stack traces
stackTraceLimit*required number

ErrorResponseError

Name Type Description
body*requiredDEPRECATED ErrorResponse
causeDEPRECATED any
errorType*requiredDEPRECATED ErrorType
isApiClientError*requiredDEPRECATED true
isClientRequestError*requiredDEPRECATED true
isErrorResponseError*requiredDEPRECATED true
message*requiredDEPRECATED string
name*requiredDEPRECATED string
response*requiredDEPRECATED HttpClientResponse
stackDEPRECATED string
prepareStackTraceDEPRECATED Object Optional override for formatting stack traces
stackTraceLimit*requiredDEPRECATED number

Forbidden

Name Type Description
body*requiredDEPRECATED ErrorResponse
causeDEPRECATED any
errorType*requiredDEPRECATED ErrorType
isApiClientError*requiredDEPRECATED true
isClientRequestError*requiredDEPRECATED true
isErrorResponseError*requiredDEPRECATED true
isForbidden*requiredDEPRECATED true
message*requiredDEPRECATED string
name*requiredDEPRECATED "Forbidden"
response*requiredDEPRECATED HttpClientResponse
stackDEPRECATED string
prepareStackTraceDEPRECATED Object Optional override for formatting stack traces
stackTraceLimit*requiredDEPRECATED number

InternalServerError

Name Type Description
body*requiredDEPRECATED ErrorResponse
causeDEPRECATED any
errorType*requiredDEPRECATED ErrorType
isApiClientError*requiredDEPRECATED true
isClientRequestError*requiredDEPRECATED true
isErrorResponseError*requiredDEPRECATED true
isInternalServerError*requiredDEPRECATED true
message*requiredDEPRECATED string
name*requiredDEPRECATED "InternalServerError"
response*requiredDEPRECATED HttpClientResponse
stackDEPRECATED string
prepareStackTraceDEPRECATED Object Optional override for formatting stack traces
stackTraceLimit*requiredDEPRECATED number

InvalidResponseError

Dedicated error class for errors related to response serialization. Thrown when received service response can't be deserialized.

Name Type Description
cause any
errorType*required ErrorType
expectedType string
isApiClientError*required true
isInvalidResponseError*required true
message*required string
name*required string
nestedError Error
response*required any
responseBody*required any
stack string
prepareStackTrace Object Optional override for formatting stack traces
stackTraceLimit*required number

NotFound

Name Type Description
body*requiredDEPRECATED ErrorResponse
causeDEPRECATED any
errorType*requiredDEPRECATED ErrorType
isApiClientError*requiredDEPRECATED true
isClientRequestError*requiredDEPRECATED true
isErrorResponseError*requiredDEPRECATED true
isNotFound*requiredDEPRECATED true
message*requiredDEPRECATED string
name*requiredDEPRECATED "NotFound"
response*requiredDEPRECATED HttpClientResponse
stackDEPRECATED string
prepareStackTraceDEPRECATED Object Optional override for formatting stack traces
stackTraceLimit*requiredDEPRECATED number

Unauthorized

Name Type Description
body*requiredDEPRECATED ErrorResponse
causeDEPRECATED any
errorType*requiredDEPRECATED ErrorType
isApiClientError*requiredDEPRECATED true
isClientRequestError*requiredDEPRECATED true
isErrorResponseError*requiredDEPRECATED true
isUnauthorized*requiredDEPRECATED true
message*requiredDEPRECATED string
name*requiredDEPRECATED "Unauthorized"
response*requiredDEPRECATED HttpClientResponse
stackDEPRECATED string
prepareStackTraceDEPRECATED Object Optional override for formatting stack traces
stackTraceLimit*requiredDEPRECATED number

UserAppStateLimitsExceeded

Name Type Description
body*requiredDEPRECATED ErrorResponse
causeDEPRECATED any
errorType*requiredDEPRECATED ErrorType
isApiClientError*requiredDEPRECATED true
isClientRequestError*requiredDEPRECATED true
isErrorResponseError*requiredDEPRECATED true
isUserAppStateLimitsExceeded*requiredDEPRECATED true
message*requiredDEPRECATED string
name*requiredDEPRECATED "UserAppStateLimitsExceeded"
response*requiredDEPRECATED HttpClientResponse
stackDEPRECATED string
prepareStackTraceDEPRECATED Object Optional override for formatting stack traces
stackTraceLimit*requiredDEPRECATED number

AppState

Name Type Description
modificationInfo ModificationInfo
validUntilTime null | string Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601
value*required string

AppStates

extends Array<ListAppState>

Name Type Description
[unscopables]*required Object

Is an object whose properties have the value 'true' when they will be absent when used in a 'with' statement.

length*required number Gets or sets the length of the array. This is a number one higher than the highest index in the array.

Error

Name Type
code*required number
details ErrorDetails
message*required string

ErrorDetails

Name Type Description
errorCode ErrorDetailsErrorCode

Error code indicating the reason why the request failed

  • AppStateOverallSizeLimitExceeded - The overall size limit for the combined size of app states of this app was exceeded
  • UserAppStateSizeLimitExceeded - The user app state content exceeded the size limit for a single user app state
  • UserAppStateCountLimitExceeded - The maximum number of user app states for this user and app was exceeded

ErrorResponse

Name Type
error*required Error

ListAppState

Name Type Description
key*required string
modificationInfo ModificationInfo
validUntilTime null | string Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601
value string

ListUserAppState

Name Type Description
key*required string
modificationInfo ModificationInfo
validUntilTime null | string Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601
value string

ModificationInfo

Name Type
lastModifiedBy*required string
lastModifiedTime*required Date

PersistenceState

Name Type Description
modificationInfo ModificationInfo
validUntilTime null | string Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601
value string

UserAppState

Name Type Description
modificationInfo ModificationInfo
validUntilTime null | string Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601
value*required string

UserAppStates

extends Array<ListUserAppState>

Name Type Description
[unscopables]*required Object

Is an object whose properties have the value 'true' when they will be absent when used in a 'with' statement.

length*required number Gets or sets the length of the array. This is a number one higher than the highest index in the array.

Enums

ErrorDetailsErrorCode

Error code indicating the reason why the request failed

  • AppStateOverallSizeLimitExceeded - The overall size limit for the combined size of app states of this app was exceeded
  • UserAppStateSizeLimitExceeded - The user app state content exceeded the size limit for a single user app state
  • UserAppStateCountLimitExceeded - The maximum number of user app states for this user and app was exceeded

Enum keys

AppStateOverallSizeLimitExceeded | UserAppStateCountLimitExceeded | UserAppStateSizeLimitExceeded

Readme

Keywords

none

Package Sidebar

Install

npm i @dynatrace-sdk/client-state

Weekly Downloads

144

Version

1.6.0

License

Apache-2.0

Unpacked Size

240 kB

Total Files

108

Last publish

Collaborators

  • stefan.wolfsteiner.dynatrace
  • dynatrace-nodejs
  • wasserb