cloreai 0.1.18 → 1.0.0

package/README.md

@@ -0,0 +1,286 @@
+# cloreai
+
+> CLORE.AI API client
+
+Особенности:
+
+- Базируется на [axios](https://github.com/axios/axios)
+- Защищает от превышения rate limit (ошибки 429) через
+  [p-queue](https://github.com/sindresorhus/p-queue)
+- Поддерживает GigaSPOT
+
+Официальная документация: [clore.ai/api-docs](https://clore.ai/api-docs)
+
+Официальная документация GigaSPOT:
+[gigaspot-api-docs.clore.ai](https://gigaspot-api-docs.clore.ai)
+
+## Установка
+
+```shell
+npm install cloreai
+```
+
+## Использование
+
+### Создание экземпляра
+
+```typescript
+import CloreAI from 'cloreai'
+
+const cloreai = new CloreAI({
+  apiKey: '<API_KEY>', // (required)
+  axiosOptions: {}, // (optional) Axios instance options https://github.com/axios/axios
+  queueOptions: {}, // (optional) Queue instance options https://github.com/sindresorhus/p-queue
+  queueOptionsCreateOrder: {}, // (optional) Create order queue instance options https://github.com/sindresorhus/p-queue
+  queueOptionsGigaspot: {}, //  (optional) Gigaspot queue instance options https://github.com/sindresorhus/p-queue
+})
+```
+
+### 1. wallets
+
+```typescript
+const wallets = await cloreai.wallets()
+```
+
+### 2. my_servers
+
+```typescript
+const myServers = await cloreai.myServers()
+```
+
+### 3. server_config
+
+```typescript
+const serverConfig = await cloreai.serverConfig({
+  server_name: 'server_name',
+})
+```
+
+### 4. marketplace
+
+```typescript
+const marketplace = await cloreai.marketplace()
+```
+
+### 5. my_orders
+
+```typescript
+const myOrders = await cloreai.myOrders() // Current orders
+const allMyOrders = await cloreai.myOrders({ return_completed: true }) // All orders
+```
+
+### 6. spot_marketplace
+
+```typescript
+const spotMarketplace = await cloreai.spotMarketplace({
+  market: 6718, // Server id
+})
+```
+
+### 7. set_server_settings
+
+```typescript
+await cloreai.setServerSettings({
+  'name': 'name', // Server name
+  'availability': true,
+  'mrl': 24,
+  'on_demand': 50,
+  'spot': 50,
+  'CLORE-Blockchain_on_demand': 50,
+  'CLORE-Blockchain_spot': 50,
+})
+```
+
+### 8. set_spot_price
+
+```typescript
+await cloreai.setSpotPrice({
+  order_id: 38176,
+  desired_price: 50,
+})
+```
+
+### 9. cancel_order
+
+```typescript
+await cloreai.cancelOrder({
+  id: 6718,
+  issue: 'issue',
+})
+```
+
+### 10. create_order
+
+```typescript
+await cloreai.createOrder({
+  type: 'on-demand',
+  currency: 'CLORE-Blockchain',
+  image: 'cloreai/jupyter:ubuntu24.04-v2',
+  renting_server: 5738,
+  ports: { 22: 'tcp', 8888: 'http' },
+  env: { SSH_PASSWORD: 'SSH_PASSWORD', JUPYTER_TOKEN: 'JUPYTER_TOKEN' },
+  jupyter_token: 'jupyter_token',
+  ssh_password: 'ssh_password',
+  required_price: 50,
+  remember_password: true,
+})
+```
+
+### 11. PoH Info
+
+```typescript
+const pohBalance = await cloreai.pohBalance()
+```
+
+### GigaSPOT
+
+#### getGigaspot
+
+```typescript
+const gigaspot = await cloreai.gigaspot.getGigaspot()
+```
+
+#### createGigaspotOrders
+
+```typescript
+import { gigaspotBaseImages } from 'cloreai'
+
+await cloreai.gigaspot.createGigaspotOrders([
+  {
+    currency: 'CLORE-Blockchain',
+    image: gigaspotBaseImages.UBUNTU, // Use the base image constant
+    renting_server: 5941,
+    price: 50,
+    oc: [
+      {
+        pl: 150,
+      },
+    ],
+  },
+])
+```
+
+#### editGigaspotOrders
+
+```typescript
+await cloreai.gigaspot.editGigaspotOrders([
+  {
+    order_id: 58991,
+    price: 50,
+    oc: [
+      {
+        pl: 150,
+      },
+    ],
+  },
+])
+```
+
+#### cancelOrders
+
+```typescript
+await cloreai.gigaspot.cancelOrders({
+  order_ids: [8383],
+})
+```
+
+### Конфигурация запросов
+
+Каждый метод принимает опциональную конфигурацию запроса для axios последним
+параметром, например:
+
+```typescript
+const marketplace = await cloreai.marketplace({
+  // axios config
+})
+```
+
+### Доступ к экземпляру axios
+
+Используйте поле `cloreai.axios`.
+
+Обратитесь к документации [axios](https://github.com/axios/axios).
+
+### Доступ к экземплярам p-queue
+
+Используйте поля:
+
+- `cloreai.queue` - для основной очереди запросов
+- `cloreai.queueCreateOrder` - для очереди запросов createOrder
+- `cloreai.gigaspot.queue` - для очереди запросов gigaspot
+
+Обратитесь к документации [p-queue](https://github.com/sindresorhus/p-queue).
+
+### Обработка ошибок
+
+Библиотека экспортирует следующие виды ошибок:
+
+- `DatabaseError`
+- `InvalidInputDataError`
+- `InvalidApiTokenError`
+- `InvalidEndpointError`
+- `ExceededError`
+- `OtherError`
+- `UnknownError`
+
+Все эти ошибки наследуются от `AxiosError`.
+
+Проверяйте тип ошибки через оператор `instanceof`:
+
+```typescript
+import { AxiosError } from 'axios'
+import { ExceededError } from 'cloreai'
+
+try {
+  const marketplace = await cloreai.marketplace()
+} catch (error) {
+  if (error instanceof AxiosError) {
+    console.log('AxiosError')
+
+    if (error instanceof ExceededError) {
+      console.log('ExceededError')
+    }
+  } else {
+    throw error
+  }
+}
+```
+
+### Rate limit
+
+Все методы защищены от превышения rate limit через
+[p-queue](https://github.com/sindresorhus/p-queue), они автоматически
+задерживаются на нужное время, чтобы избежать превышения лимита.
+
+Значения rate limit по умолчанию доступны как константы:
+
+```typescript
+import {
+  RATE_LIMIT,
+  RATE_LIMIT_CREATE_ORDER,
+  RATE_LIMIT_GIGASPOT,
+} from 'cloreai'
+
+console.log(RATE_LIMIT)
+console.log(RATE_LIMIT_CREATE_ORDER)
+console.log(RATE_LIMIT_GIGASPOT)
+```
+
+Можно задать собственные значение rate limit для каждой очереди запросов:
+
+```typescript
+import CloreAI from 'cloreai'
+
+const cloreai = new CloreAI({
+  apiKey: '<API_KEY>',
+  queueOptions: {
+    interval: 10000, // 10 seconds
+  },
+  queueOptionsCreateOrder: {
+    interval: 10000, // 10 seconds
+  },
+  queueOptionsGigaspot: {
+    interval: 10000, // 10 seconds
+  },
+})
+```

package/build/{cloreai/CloreAI.d.ts → CloreAI.d.ts}

@@ -1,38 +1,34 @@
 import { type AxiosInstance, type AxiosRequestConfig } from 'axios';
 import PQueue from 'p-queue';
 import type { CancelOrderRequestData, CancelOrderResponseData } from './endpoints/cancelOrder.js';
-import type { CancelOrdersRequestData, CancelOrdersResponseData } from './endpoints/cancelOrders.js';
-import type { CreateGigaspotOrdersRequestData, CreateGigaspotOrdersResponseData } from './endpoints/createGigaspotOrders.js';
 import type { CreateOrderRequestData, CreateOrderResponseData } from './endpoints/createOrder.js';
-import type { EditGigaspotOrdersRequestData, EditGigaspotOrdersResponseData } from './endpoints/editGigaspotOrders.js';
-import type { GetGigaspotResponseData } from './endpoints/getGigaspot.js';
 import type { MarketplaceResponseData } from './endpoints/marketplace.js';
 import type { MyOrdersRequestParams, MyOrdersResponseData } from './endpoints/myOrders.js';
 import type { MyServersResponseData } from './endpoints/myServers.js';
+import type { PohBalanceResponseData } from './endpoints/pohBalance.js';
 import type { ServerConfigRequestData, ServerConfigResponseData } from './endpoints/serverConfig.js';
 import type { SetServerSettingsRequestData, SetServerSettingsResponseData } from './endpoints/setServerSettings.js';
 import type { SetSpotPriceRequestData, SetSpotPriceResponseData } from './endpoints/setSpotPrice.js';
 import type { SpotMarketplaceRequestParams, SpotMarketplaceResponseData } from './endpoints/spotMarketplace.js';
 import type { WalletsResponseData } from './endpoints/wallets.js';
 import type { Config } from './types.js';
+import Gigaspot from './Gigaspot.js';
 declare class CloreAI {
     axios: AxiosInstance;
-    rateLimitQueue: PQueue;
-    rateLimitQueueCreateOrder: PQueue;
+    queue: PQueue;
+    queueCreateOrder: PQueue;
+    gigaspot: Gigaspot;
     constructor(config: Config);
     wallets(config?: AxiosRequestConfig): Promise<WalletsResponseData>;
     myServers(config?: AxiosRequestConfig): Promise<MyServersResponseData>;
     serverConfig(data: ServerConfigRequestData, config?: AxiosRequestConfig): Promise<ServerConfigResponseData>;
     marketplace(config?: AxiosRequestConfig): Promise<MarketplaceResponseData>;
-    myOrders(params: MyOrdersRequestParams, config?: AxiosRequestConfig): Promise<MyOrdersResponseData>;
+    myOrders(params?: MyOrdersRequestParams, config?: AxiosRequestConfig): Promise<MyOrdersResponseData>;
     spotMarketplace(params: SpotMarketplaceRequestParams, config?: AxiosRequestConfig): Promise<SpotMarketplaceResponseData>;
     setServerSettings(data: SetServerSettingsRequestData, config?: AxiosRequestConfig): Promise<SetServerSettingsResponseData>;
     setSpotPrice(data: SetSpotPriceRequestData, config?: AxiosRequestConfig): Promise<SetSpotPriceResponseData>;
     cancelOrder(data: CancelOrderRequestData, config?: AxiosRequestConfig): Promise<CancelOrderResponseData>;
     createOrder(data: CreateOrderRequestData, config?: AxiosRequestConfig): Promise<CreateOrderResponseData>;
-    getGigaspot(config?: AxiosRequestConfig): Promise<GetGigaspotResponseData>;
-    createGigaspotOrders(data: CreateGigaspotOrdersRequestData, config?: AxiosRequestConfig): Promise<CreateGigaspotOrdersResponseData>;
-    editGigaspotOrders(data: EditGigaspotOrdersRequestData, config?: AxiosRequestConfig): Promise<EditGigaspotOrdersResponseData>;
-    cancelOrders(data: CancelOrdersRequestData, config?: AxiosRequestConfig): Promise<CancelOrdersResponseData>;
+    pohBalance(config?: AxiosRequestConfig): Promise<PohBalanceResponseData>;
 }
 export default CloreAI;

package/build/{cloreai/CloreAI.js → CloreAI.js}

@@ -1,27 +1,29 @@
 import axios from 'axios';
 import PQueue from 'p-queue';
-import { priorityLevels, RATE_LIMIT, RATE_LIMIT_CREATE_ORDER, statusCodes } from '../common/constants.js';
-import { DatabaseError, ExceededError, InvalidApiTokenError, InvalidEndpointError, InvalidInputDataError, OtherError, UnknownError } from '../common/errors.js';
-import { getErrorMessage, getQueueOptions } from '../common/helpers.js';
+import { RATE_LIMIT, RATE_LIMIT_CREATE_ORDER } from './constants.js';
+import { DatabaseError, ExceededError, InvalidApiTokenError, InvalidEndpointError, InvalidInputDataError, OtherError, UnknownError } from './errors.js';
+import Gigaspot from './Gigaspot.js';
+import { getQueueOptions, priorityLevels, statusCodes } from './helpers.js';
 class CloreAI {
     axios;
-    rateLimitQueue;
-    rateLimitQueueCreateOrder;
+    queue;
+    queueCreateOrder;
+    gigaspot;
     constructor(config) {
-        this.rateLimitQueue = new PQueue({
+        this.queue = new PQueue({
             interval: RATE_LIMIT,
             intervalCap: 1,
             concurrency: 1,
-            ...config.rateLimitQueueOptions,
+            ...config.queueOptions,
         });
-        this.rateLimitQueueCreateOrder = new PQueue({
+        this.queueCreateOrder = new PQueue({
             interval: RATE_LIMIT_CREATE_ORDER,
             intervalCap: 1,
             concurrency: 1,
-            ...config.rateLimitQueueOptionsCreateOrder,
+            ...config.queueOptionsCreateOrder,
         });
         this.axios = axios.create({
-            ...config.axiosConfig,
+            ...config.axiosOptions,
             baseURL: 'https://api.clore.ai/v1',
         });
         this.axios.interceptors.request.use((request) => {
@@ -32,7 +34,9 @@ class CloreAI {
             if (response.data.code === statusCodes.NORMAL) {
                 return response;
             }
-            const errorMessage = getErrorMessage(response.data.code, response.data.error);
+            const errorMessage = response.data.error != null
+                ? `Code "${response.data.code}", error "${response.data.error}"`
+                : `Code "${response.data.code}"`;
             const axiosErrorParameters = [
                 errorMessage,
                 undefined,
@@ -57,93 +61,72 @@ class CloreAI {
                     throw new UnknownError(...axiosErrorParameters);
             }
         });
+        this.gigaspot = new Gigaspot(config, this.axios);
     }
     async wallets(config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.get('/wallets', config);
         }, getQueueOptions(priorityLevels.NORMAL, config));
         return response.data;
     }
     async myServers(config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.get('/my_servers', config);
         }, getQueueOptions(priorityLevels.NORMAL, config));
         return response.data;
     }
     async serverConfig(data, config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.get('/server_config', { ...config, data });
         }, getQueueOptions(priorityLevels.NORMAL, config));
         return response.data;
     }
     async marketplace(config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.get('/marketplace', config);
         }, getQueueOptions(priorityLevels.NORMAL, config));
         return response.data;
     }
     async myOrders(params, config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.get('/my_orders', { ...config, params });
         }, getQueueOptions(priorityLevels.NORMAL, config));
         return response.data;
     }
     async spotMarketplace(params, config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.get('/spot_marketplace', { ...config, params });
         }, getQueueOptions(priorityLevels.NORMAL, config));
         return response.data;
     }
     async setServerSettings(data, config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.post('/set_server_settings', data, config);
         }, getQueueOptions(priorityLevels.HIGH, config));
         return response.data;
     }
     async setSpotPrice(data, config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.post('/set_spot_price', data, config);
         }, getQueueOptions(priorityLevels.HIGH, config));
         return response.data;
     }
     async cancelOrder(data, config) {
-        const response = await this.rateLimitQueue.add(async () => {
+        const response = await this.queue.add(async () => {
             return await this.axios.post('/cancel_order', data, config);
         }, getQueueOptions(priorityLevels.HIGH, config));
         return response.data;
     }
     async createOrder(data, config) {
-        const response = await this.rateLimitQueueCreateOrder.add(async () => {
+        const response = await this.queueCreateOrder.add(async () => {
             return await this.axios.post('/create_order', data, config);
         }, getQueueOptions(priorityLevels.HIGHEST, config));
         return response.data;
     }
-    async getGigaspot(config) {
-        return await this.rateLimitQueue.add(async () => {
-            const response = await this.axios.get('/get_gigaspot', config);
-            const snapshot = await axios.get(response.data.v1_snapshot_url);
-            return {
-                ...response.data,
-                snapshot: snapshot.data,
-            };
+    async pohBalance(config) {
+        const response = await this.queue.add(async () => {
+            return await this.axios.get('/poh_balance', config);
         }, getQueueOptions(priorityLevels.NORMAL, config));
-    }
-    async createGigaspotOrders(data, config) {
-        const response = await this.rateLimitQueue.add(async () => {
-            return await this.axios.post('/create_gigaspot_orders', data, config);
-        }, getQueueOptions(priorityLevels.HIGH, config));
-        return response.data;
-    }
-    async editGigaspotOrders(data, config) {
-        const response = await this.rateLimitQueue.add(async () => {
-            return await this.axios.post('/edit_gigaspot_orders', data, config);
-        }, getQueueOptions(priorityLevels.HIGH, config));
-        return response.data;
-    }
-    async cancelOrders(data, config) {
-        const response = await this.rateLimitQueue.add(async () => {
-            return await this.axios.post('/cancel_orders', data, config);
-        }, getQueueOptions(priorityLevels.HIGH, config));
         return response.data;
     }
 }

package/build/Gigaspot.d.ts

@@ -0,0 +1,17 @@
+import { type AxiosInstance, type AxiosRequestConfig } from 'axios';
+import PQueue from 'p-queue';
+import type { CancelOrdersRequestData, CancelOrdersResponseData } from './endpoints/cancelOrders.js';
+import type { CreateGigaspotOrdersRequestData, CreateGigaspotOrdersResponseData } from './endpoints/createGigaspotOrders.js';
+import type { EditGigaspotOrdersRequestData, EditGigaspotOrdersResponseData } from './endpoints/editGigaspotOrders.js';
+import type { GetGigaspotResponseData } from './endpoints/getGigaspot.js';
+import type { Config } from './types.js';
+declare class Gigaspot {
+    queue: PQueue;
+    private readonly axios;
+    constructor(config: Config, axios: AxiosInstance);
+    getGigaspot(config?: AxiosRequestConfig): Promise<GetGigaspotResponseData>;
+    createGigaspotOrders(data: CreateGigaspotOrdersRequestData, config?: AxiosRequestConfig): Promise<CreateGigaspotOrdersResponseData>;
+    editGigaspotOrders(data: EditGigaspotOrdersRequestData, config?: AxiosRequestConfig): Promise<EditGigaspotOrdersResponseData>;
+    cancelOrders(data: CancelOrdersRequestData, config?: AxiosRequestConfig): Promise<CancelOrdersResponseData>;
+}
+export default Gigaspot;

package/build/Gigaspot.js

@@ -0,0 +1,46 @@
+import axios from 'axios';
+import PQueue from 'p-queue';
+import { RATE_LIMIT_GIGASPOT } from './constants.js';
+import { getQueueOptions, priorityLevels } from './helpers.js';
+class Gigaspot {
+    queue;
+    axios;
+    constructor(config, axios) {
+        this.queue = new PQueue({
+            interval: RATE_LIMIT_GIGASPOT,
+            intervalCap: 1,
+            concurrency: 1,
+            ...config.queueOptionsGigaspot,
+        });
+        this.axios = axios;
+    }
+    async getGigaspot(config) {
+        return await this.queue.add(async () => {
+            const response = await this.axios.get('/get_gigaspot', config);
+            const snapshot = await axios.get(response.data.v1_snapshot_url);
+            return {
+                ...response.data,
+                snapshot: snapshot.data,
+            };
+        }, getQueueOptions(priorityLevels.NORMAL, config));
+    }
+    async createGigaspotOrders(data, config) {
+        const response = await this.queue.add(async () => {
+            return await this.axios.post('/create_gigaspot_orders', data, config);
+        }, getQueueOptions(priorityLevels.HIGH, config));
+        return response.data;
+    }
+    async editGigaspotOrders(data, config) {
+        const response = await this.queue.add(async () => {
+            return await this.axios.post('/edit_gigaspot_orders', data, config);
+        }, getQueueOptions(priorityLevels.HIGH, config));
+        return response.data;
+    }
+    async cancelOrders(data, config) {
+        const response = await this.queue.add(async () => {
+            return await this.axios.post('/cancel_orders', data, config);
+        }, getQueueOptions(priorityLevels.HIGH, config));
+        return response.data;
+    }
+}
+export default Gigaspot;

package/build/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const RATE_LIMIT = 1800;
+export declare const RATE_LIMIT_CREATE_ORDER = 5000;
+export declare const RATE_LIMIT_GIGASPOT = 1800;
+export declare const gigaspotBaseImages: {
+    UBUNTU: string;
+    HIVEOS: string;
+};

package/build/constants.js

@@ -0,0 +1,7 @@
+export const RATE_LIMIT = 1800;
+export const RATE_LIMIT_CREATE_ORDER = 5000;
+export const RATE_LIMIT_GIGASPOT = 1800;
+export const gigaspotBaseImages = {
+    UBUNTU: 'a3f9c4d7e5b088d8a0bff880',
+    HIVEOS: 'c9a4e2f6b7d488d8f0bab0ff',
+};

package/build/endpoints/cancelOrder.d.ts

@@ -0,0 +1,6 @@
+import type { ResponseData } from '../types.js';
+export interface CancelOrderRequestData {
+    id: number;
+    issue?: string;
+}
+export type CancelOrderResponseData = ResponseData;

package/build/{cloreai/endpoints → endpoints}/cancelOrders.d.ts

@@ -3,5 +3,5 @@ export interface CancelOrdersRequestData {
     order_ids: number[];
 }
 export interface CancelOrdersResponseData extends ResponseData {
-    failed_to_cancel: number[];
+    failed_to_cancel: string[];
 }

package/build/{cloreai/endpoints → endpoints}/createGigaspotOrders.d.ts

@@ -1,5 +1,4 @@
-import type { Currency } from '../../common/types.js';
-import type { ResponseData } from '../types.js';
+import type { Currency, ResponseData } from '../types.js';
 export interface CreateGigaspotOrdersRequestDataOrderOverclock {
     pl: number;
     core_lock?: number;

package/build/{common/endpoints → endpoints}/createOrder.d.ts

@@ -1,4 +1,4 @@
-import type { Currency, OrderType } from '../types.js';
+import type { Currency, OrderType, ResponseData } from '../types.js';
 export interface CreateOrderRequestDataBase {
     type: OrderType;
     currency: Currency;
@@ -22,4 +22,5 @@ export interface CreateOrderRequestDataSpot extends CreateOrderRequestDataBase {
     type: 'spot';
     spotprice: number;
 }
-export type CreateOrderRequestDataCommon = CreateOrderRequestDataOnDemand | CreateOrderRequestDataSpot;
+export type CreateOrderRequestData = CreateOrderRequestDataOnDemand | CreateOrderRequestDataSpot;
+export type CreateOrderResponseData = ResponseData;

package/build/{cloreai/endpoints → endpoints}/getGigaspot.d.ts

@@ -1,5 +1,4 @@
-import type { Currency, Pricing } from '../../common/types.js';
-import type { ResponseData } from '../types.js';
+import type { Currency, Pricing, ResponseData } from '../types.js';
 export interface GetGigaspotResponseDataSnapshotServerBid {
     owner: number;
     id: number;

package/build/endpoints/marketplace.d.ts

@@ -0,0 +1,24 @@
+import type { Currency, Price, ResponseData, Specs } from '../types.js';
+export interface MarketplaceResponseDataServerRating {
+    avg: number;
+    cnt: number;
+}
+export interface MarketplaceResponseDataServer {
+    id: number;
+    owner: number;
+    mrl: number;
+    price: Price;
+    rented: boolean;
+    specs: Specs;
+    reliability: number;
+    allowed_coins: Currency[];
+    rating: MarketplaceResponseDataServerRating;
+    gpu_array: string[];
+    gigaspot: boolean;
+    oc?: boolean;
+    cuda_version: string;
+}
+export interface MarketplaceResponseData extends ResponseData {
+    servers: MarketplaceResponseDataServer[];
+    my_servers: number[];
+}