https://github.com/gravity-ui/sdk
SDK implementing work with REST/GRPC APIs
https://github.com/gravity-ui/sdk
Last synced: 8 months ago
JSON representation
SDK implementing work with REST/GRPC APIs
- Host: GitHub
- URL: https://github.com/gravity-ui/sdk
- Owner: gravity-ui
- License: mit
- Created: 2023-08-21T20:04:51.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-04T16:23:46.000Z (over 1 year ago)
- Last Synced: 2024-12-30T18:02:08.688Z (over 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 385 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# @gravity-ui/sdk · [](https://www.npmjs.com/package/@gravity-ui/sdk) [](https://github.com/gravity-ui/sdk/actions/workflows/ci.yml?query=branch:main)
SDK implementing work with REST/GRPC APIs
## Install
```shell
npm install --save-dev @gravity-ui/sdk
```
## Usage
You need to import `sdkFactory` and `Schema`, and create an instance of the class.
If the schema is not divided into scopes:
```typescript
import sdkFactory from '@gravity-ui/sdk';
import type Schema from '';
const config = {
csrfToken: 'secret-token',
endpoint: '/gateway',
};
const sdk = sdkFactory<{root: typeof Schema}>(config);
```
If the schema is divided into scopes:
```typescript
import sdkFactory from '@gravity-ui/sdk';
import type Schema from '';
import type LocalSchema from '../../shared/schemas';
const config = {
csrfToken: 'secret-token',
endpoint: '/gateway',
};
const sdk = sdkFactory<{root: typeof Schema; local: typeof LocalSchema}>(config);
```
Structure of `config`:
```typescript
import {AxiosRequestConfig} from 'axios';
interface SdkConfig {
// Custom Axios settings
axiosConfig?: AxiosRequestConfig;
// CSRF-token
csrfToken?: string;
// The endpoint to which the request from the client will be sent. By default, "/api" is used
endpoint?: string;
// Custom error handler. If the configuration is not specified, the default one is used
handleRequestError?: (error: unknown) => any;
}
```
In the code, the invocation of the SDK method looks like this:
```javascript
sdk...(data, options); // => returns a CancelablePromise
```
If the default endpoint value `/api` is specified, the full request path will look like this:
`/api/:scope/:service/:action`
There is a special scope called `root`. Its methods can be called without explicitly specifying the scope.
The following calls are equivalent:
`sdk.root..(data, options);`
`sdk..(data, options);`
But the full request path will always include the scope:
`/api/root/:service/:action`
Structure of `options`:
```typescript
interface SdkOptions {
// Request identifier. The previous request with the same identifier will be canceled
concurrentId?: string;
// Ability to specify a specific number of retries for certain endpoints. By default, the number of retries is 0
retries?: number;
// Ability to specify a specific timeout for certain endpoints.
// By default, the configuration is taken from axiosConfig or set to 60 seconds
timeout?: number;
// Ability to specify specific headers when making a call
headers?: Record;
}
```
## Invoking External Methods
Through the `sdk`, you have the ability to make calls to external methods that are not defined in the schemas. Such a call looks like this:
`sdk(config, options);`
The argument `config` has the type `AxiosRequestConfig`, and the argument options has the type `SdkOptions` described above.
## CancellablePromise
For the convenience of creating cancelable promises, the package exports a class called `CancellablePromise(promise: Promise, cancel: () => void)`.
## Additional methods
### sdk.setLang()
Allows setting the user's language, which will be passed to all invoked endpoints through a special `accept-language` header.
### sdk.setDefaultHeader()
Allows setting base headers that will be passed to all invoked endpoints.