algosdk 2.8.0 → 3.0.0-beta.1

package/src/client/client.ts

@@ -1,23 +1,73 @@
-import { Buffer } from 'buffer';
-import * as utils from '../utils/utils';
+import * as utils from '../utils/utils.js';
 import {
   BaseHTTPClient,
   BaseHTTPClientResponse,
   Query,
-} from './baseHTTPClient';
-import { TokenHeader, URLTokenBaseHTTPClient } from './urlTokenBaseHTTPClient';
+} from './baseHTTPClient.js';
+import {
+  TokenHeader,
+  URLTokenBaseHTTPClient,
+} from './urlTokenBaseHTTPClient.js';
 
 interface ErrorWithAdditionalInfo extends Error {
   rawResponse: string | null;
   statusCode: number;
 }
 
-export interface HTTPClientResponse {
-  body: Uint8Array | any; // when content-type=JSON, body is a JSON object, otherwise it's a Uint8Array
+export class HTTPClientResponse {
+  /**
+   * The raw response bytes
+   */
+  body: Uint8Array;
+  /**
+   * If the expected response type is JSON, this is the response bytes converted to a string.
+   */
   text?: string;
+  format: 'application/msgpack' | 'application/json';
   headers: Record<string, string>;
   status: number;
   ok: boolean;
+
+  constructor(options: {
+    body: Uint8Array;
+    text?: string;
+    format: 'application/msgpack' | 'application/json';
+    headers: Record<string, string>;
+    status: number;
+    ok: boolean;
+  }) {
+    this.body = options.body;
+    this.text = options.text;
+    this.format = options.format;
+    this.headers = options.headers;
+    this.status = options.status;
+    this.ok = options.ok;
+  }
+
+  /**
+   * Returns the response body as a string, ready to be parsed as JSON.
+   */
+  getJSONText(): string {
+    if (this.text === undefined) {
+      throw new Error(
+        `Response body does not contain JSON data. Format is ${this.format}`
+      );
+    }
+    return this.text;
+  }
+
+  /**
+   * Parses the response body as JSON with the given options.
+   */
+  parseBodyAsJSON(jsonOptions: utils.ParseJSONOptions) {
+    if (this.text === undefined) {
+      throw new Error(
+        `Response body does not contain JSON data. Format is ${this.format}`
+      );
+    }
+    // eslint-disable-next-line no-use-before-define
+    return HTTPClient.parseJSON(this.text, this.status, jsonOptions);
+  }
 }
 
 /**
@@ -38,9 +88,12 @@ function removeFalsyOrEmpty(obj: Record<string, any>) {
  * See https://codereview.stackexchange.com/a/162418
  * Used to ensure all headers are lower-case and to work more easily with them
  */
-function tolowerCaseKeys(o: object): object {
+function tolowerCaseKeys(o: Record<string, any>): Record<string, any> {
   /* eslint-disable no-param-reassign,no-return-assign,no-sequences */
-  return Object.keys(o).reduce((c, k) => ((c[k.toLowerCase()] = o[k]), c), {});
+  return Object.keys(o).reduce(
+    (c, k) => ((c[k.toLowerCase()] = o[k]), c),
+    {} as Record<string, any>
+  );
   /* eslint-enable no-param-reassign,no-return-assign,no-sequences */
 }
 
@@ -70,7 +123,7 @@ function getAcceptFormat(
  * It takes care of setting the proper "Accept" header and of
  * decoding the JSON outputs.
  */
-export default class HTTPClient {
+export class HTTPClient {
   private bc: BaseHTTPClient;
 
   /**
@@ -107,8 +160,7 @@ export default class HTTPClient {
   }
 
   /**
-   * Parse JSON using either the built-in JSON.parse or utils.parseJSON
-   * depending on whether jsonOptions are provided or not
+   * Parse JSON using utils.parseJSON
    *
    * @param text - JSON data
    * @param status - Status of the response (used in case parseJSON fails)
@@ -118,15 +170,15 @@ export default class HTTPClient {
   public static parseJSON(
     text: string,
     status: number,
-    jsonOptions: utils.JSONOptions = {}
+    jsonOptions: utils.ParseJSONOptions
   ) {
     try {
-      if (Object.keys(jsonOptions).length === 0) {
-        return text && JSON.parse(text);
+      if (!text) {
+        return null;
       }
-      return text && utils.parseJSON(text, jsonOptions);
+      return utils.parseJSON(text, jsonOptions);
     } catch (err_) {
-      const err: ErrorWithAdditionalInfo = err_;
+      const err = err_ as ErrorWithAdditionalInfo;
       // return the raw response if the response parsing fails
       err.rawResponse = text || null;
       // return the http status code if the response parsing fails
@@ -151,10 +203,10 @@ export default class HTTPClient {
       return new Uint8Array(0); // empty Uint8Array
     }
     if (requestHeaders['content-type'] === 'application/json') {
-      return new Uint8Array(Buffer.from(JSON.stringify(data)));
+      return new TextEncoder().encode(utils.stringifyJSON(data));
     }
     if (typeof data === 'string') {
-      return new Uint8Array(Buffer.from(data));
+      return new TextEncoder().encode(data);
     }
     if (data instanceof Uint8Array) {
       return data;
@@ -171,27 +223,21 @@ export default class HTTPClient {
    */
   private static prepareResponse(
     res: BaseHTTPClientResponse,
-    format: 'application/msgpack' | 'application/json',
-    parseBody: boolean,
-    jsonOptions: utils.JSONOptions = {}
+    format: 'application/msgpack' | 'application/json'
   ): HTTPClientResponse {
-    let { body } = res;
-    let text;
+    const { body } = res;
+    let text: string | undefined;
 
     if (format !== 'application/msgpack') {
-      text = (body && Buffer.from(body).toString()) || '';
-    }
-
-    if (parseBody && format === 'application/json') {
-      body = HTTPClient.parseJSON(text, res.status, jsonOptions);
+      text = (body && new TextDecoder().decode(body)) || '';
     }
 
-    return {
+    return new HTTPClientResponse({
       ...res,
-      body,
+      format,
       text,
       ok: Math.trunc(res.status / 100) === 2,
-    };
+    });
   }
 
   /**
@@ -200,13 +246,12 @@ export default class HTTPClient {
    * by adding the status and preparing the internal response
    * @private
    */
-  private static prepareResponseError(err) {
+  private static prepareResponseError(err: any) {
     if (err.response) {
       // eslint-disable-next-line no-param-reassign
       err.response = HTTPClient.prepareResponse(
         err.response,
-        'application/json',
-        true
+        'application/json'
       );
       // eslint-disable-next-line no-param-reassign
       err.status = err.response.status;
@@ -216,33 +261,39 @@ export default class HTTPClient {
 
   /**
    * Send a GET request.
-   * @param relativePath - The path of the request.
-   * @param query - An object containing the query parameters of the request.
-   * @param requestHeaders - An object containing additional request headers to use.
-   * @param jsonOptions - Options object to use to decode JSON responses. See
-   *   utils.parseJSON for the options available.
-   * @param parseBody - An optional boolean indicating whether the response body should be parsed
+   *
+   * @param options - The options to use for the request.
+   * @param options.relativePath - The path of the request.
+   * @param options.query - An object containing the query parameters of the request.
+   * @param options.requestHeaders - An object containing additional request headers to use.
    *   or not.
+   * @param options.customOptions - An object containing additional options to pass to the
+   *   underlying BaseHTTPClient instance.
    * @returns Response object.
    */
-  async get(
-    relativePath: string,
-    query?: Query<any>,
-    requestHeaders: Record<string, string> = {},
-    jsonOptions: utils.JSONOptions = {},
-    parseBody: boolean = true
-  ): Promise<HTTPClientResponse> {
+  async get({
+    relativePath,
+    query,
+    requestHeaders,
+    customOptions,
+  }: {
+    relativePath: string;
+    query?: Query<any>;
+    requestHeaders?: Record<string, string>;
+    customOptions?: Record<string, unknown>;
+  }): Promise<HTTPClientResponse> {
     const format = getAcceptFormat(query);
-    const fullHeaders = { ...requestHeaders, accept: format };
+    const fullHeaders = { ...(requestHeaders ?? {}), accept: format };
 
     try {
       const res = await this.bc.get(
         relativePath,
-        removeFalsyOrEmpty(query),
-        fullHeaders
+        query ? removeFalsyOrEmpty(query) : undefined,
+        fullHeaders,
+        customOptions
       );
 
-      return HTTPClient.prepareResponse(res, format, parseBody, jsonOptions);
+      return HTTPClient.prepareResponse(res, format);
     } catch (err) {
       throw HTTPClient.prepareResponseError(err);
     }
@@ -252,17 +303,24 @@ export default class HTTPClient {
    * Send a POST request.
    * If no content-type present, adds the header "content-type: application/json"
    * and data is serialized in JSON (if not empty)
+   * @param options - The options to use for the request.
    */
-  async post(
-    relativePath: string,
-    data: any,
-    requestHeaders: Record<string, string> = {},
-    query?: Query<any>,
-    parseBody: boolean = true
-  ): Promise<HTTPClientResponse> {
+  async post({
+    relativePath,
+    data,
+    query,
+    requestHeaders,
+    customOptions,
+  }: {
+    relativePath: string;
+    data: any;
+    query?: Query<any>;
+    requestHeaders?: Record<string, string>;
+    customOptions?: Record<string, unknown>;
+  }): Promise<HTTPClientResponse> {
     const fullHeaders = {
       'content-type': 'application/json',
-      ...tolowerCaseKeys(requestHeaders),
+      ...tolowerCaseKeys(requestHeaders ?? {}),
     };
 
     try {
@@ -270,10 +328,11 @@ export default class HTTPClient {
         relativePath,
         HTTPClient.serializeData(data, fullHeaders),
         query,
-        fullHeaders
+        fullHeaders,
+        customOptions
       );
 
-      return HTTPClient.prepareResponse(res, 'application/json', parseBody);
+      return HTTPClient.prepareResponse(res, 'application/json');
     } catch (err) {
       throw HTTPClient.prepareResponseError(err);
     }
@@ -283,25 +342,38 @@ export default class HTTPClient {
    * Send a DELETE request.
    * If no content-type present, adds the header "content-type: application/json"
    * and data is serialized in JSON (if not empty)
+   * @param options - The options to use for the request.
    */
-  async delete(
-    relativePath: string,
-    data: any,
-    requestHeaders: Record<string, string> = {},
-    parseBody: boolean = true
-  ) {
+  async delete({
+    relativePath,
+    data,
+    requestHeaders,
+    customOptions,
+  }: {
+    relativePath: string;
+    data: any;
+    requestHeaders?: Record<string, string>;
+    customOptions?: Record<string, unknown>;
+  }) {
     const fullHeaders = {
       'content-type': 'application/json',
-      ...tolowerCaseKeys(requestHeaders),
+      ...tolowerCaseKeys(requestHeaders ?? {}),
     };
 
-    const res = await this.bc.delete(
-      relativePath,
-      HTTPClient.serializeData(data, fullHeaders),
-      undefined,
-      fullHeaders
-    );
+    try {
+      const res = await this.bc.delete(
+        relativePath,
+        typeof data !== 'undefined'
+          ? HTTPClient.serializeData(data, fullHeaders)
+          : undefined,
+        undefined,
+        fullHeaders,
+        customOptions
+      );
 
-    return HTTPClient.prepareResponse(res, 'application/json', parseBody);
+      return HTTPClient.prepareResponse(res, 'application/json');
+    } catch (err) {
+      throw HTTPClient.prepareResponseError(err);
+    }
   }
 }

package/src/client/index.ts

@@ -0,0 +1,6 @@
+// Generics
+export { default as JSONRequest } from './v2/jsonrequest.js';
+export { default as ServiceClient } from './v2/serviceClient.js';
+export * from './baseHTTPClient.js';
+export * from './urlTokenBaseHTTPClient.js';
+export * from './client.js';

package/src/client/kmd.ts

@@ -1,9 +1,14 @@
-import { Buffer } from 'buffer';
-import ServiceClient from './v2/serviceClient';
-import * as txn from '../transaction';
-import { CustomTokenHeader, KMDTokenHeader } from './urlTokenBaseHTTPClient';
+import {
+  base64ToBytes,
+  bytesToBase64,
+  coerceToBytes,
+} from '../encoding/binarydata.js';
+import IntDecoding from '../types/intDecoding.js';
+import { Transaction } from '../transaction.js';
+import { CustomTokenHeader, KMDTokenHeader } from './urlTokenBaseHTTPClient.js';
+import ServiceClient from './v2/serviceClient.js';
 
-export default class Kmd extends ServiceClient {
+export class KmdClient extends ServiceClient {
   constructor(
     token: string | KMDTokenHeader | CustomTokenHeader,
     baseServer = 'http://127.0.0.1',
@@ -13,12 +18,43 @@ export default class Kmd extends ServiceClient {
     super('X-KMD-API-Token', token, baseServer, port, headers);
   }
 
+  private async get(relativePath: string): Promise<any> {
+    const res = await this.c.get({
+      relativePath,
+    });
+    return res.parseBodyAsJSON({
+      // Using SAFE for all KMD endpoints because no integers in responses should ever be too big
+      intDecoding: IntDecoding.SAFE,
+    });
+  }
+
+  private async delete(relativePath: string, data: any): Promise<any> {
+    const res = await this.c.delete({
+      relativePath,
+      data,
+    });
+    return res.parseBodyAsJSON({
+      // Using SAFE for all KMD endpoints because no integers in responses should ever be too big
+      intDecoding: IntDecoding.SAFE,
+    });
+  }
+
+  private async post(relativePath: string, data: any): Promise<any> {
+    const res = await this.c.post({
+      relativePath,
+      data,
+    });
+    return res.parseBodyAsJSON({
+      // Using SAFE for all KMD endpoints because no integers in responses should ever be too big
+      intDecoding: IntDecoding.SAFE,
+    });
+  }
+
   /**
    * version returns a VersionResponse containing a list of kmd API versions supported by this running kmd instance.
    */
   async versions() {
-    const res = await this.c.get('/versions');
-    return res.body;
+    return this.get('/versions');
   }
 
   /**
@@ -26,8 +62,7 @@ export default class Kmd extends ServiceClient {
    * returned from this endpoint, you can initialize a wallet handle with client.InitWalletHandle
    */
   async listWallets() {
-    const res = await this.c.get('/v1/wallets');
-    return res.body;
+    return this.get('/v1/wallets');
   }
 
   /**
@@ -50,10 +85,9 @@ export default class Kmd extends ServiceClient {
       wallet_name: walletName,
       wallet_driver_name: walletDriverName,
       wallet_password: walletPassword,
-      master_derivation_key: Buffer.from(walletMDK).toString('base64'),
+      master_derivation_key: bytesToBase64(walletMDK),
     };
-    const res = await this.c.post('/v1/wallet', req);
-    return res.body;
+    return this.post('/v1/wallet', req);
   }
 
   /**
@@ -72,8 +106,7 @@ export default class Kmd extends ServiceClient {
       wallet_id: walletID,
       wallet_password: walletPassword,
     };
-    const res = await this.c.post('/v1/wallet/init', req);
-    return res.body;
+    return this.post('/v1/wallet/init', req);
   }
 
   /**
@@ -85,8 +118,7 @@ export default class Kmd extends ServiceClient {
     const req = {
       wallet_handle_token: walletHandle,
     };
-    const res = await this.c.post('/v1/wallet/release', req);
-    return res.body;
+    return this.post('/v1/wallet/release', req);
   }
 
   /**
@@ -100,8 +132,7 @@ export default class Kmd extends ServiceClient {
     const req = {
       wallet_handle_token: walletHandle,
     };
-    const res = await this.c.post('/v1/wallet/renew', req);
-    return res.body;
+    return this.post('/v1/wallet/renew', req);
   }
 
   /**
@@ -121,8 +152,7 @@ export default class Kmd extends ServiceClient {
       wallet_password: walletPassword,
       wallet_name: newWalletName,
     };
-    const res = await this.c.post('/v1/wallet/rename', req);
-    return res.body;
+    return this.post('/v1/wallet/rename', req);
   }
 
   /**
@@ -134,8 +164,7 @@ export default class Kmd extends ServiceClient {
     const req = {
       wallet_handle_token: walletHandle,
     };
-    const res = await this.c.post('/v1/wallet/info', req);
-    return res.body;
+    return this.post('/v1/wallet/info', req);
   }
 
   /**
@@ -155,12 +184,9 @@ export default class Kmd extends ServiceClient {
       wallet_handle_token: walletHandle,
       wallet_password: walletPassword,
     };
-    const res = await this.c.post('/v1/master-key/export', req);
+    const res = await this.post('/v1/master-key/export', req);
     return {
-      master_derivation_key: Buffer.from(
-        res.body.master_derivation_key,
-        'base64'
-      ),
+      master_derivation_key: base64ToBytes(res.master_derivation_key),
     };
   }
 
@@ -174,10 +200,9 @@ export default class Kmd extends ServiceClient {
   async importKey(walletHandle: string, secretKey: Uint8Array) {
     const req = {
       wallet_handle_token: walletHandle,
-      private_key: Buffer.from(secretKey).toString('base64'),
+      private_key: bytesToBase64(secretKey),
     };
-    const res = await this.c.post('/v1/key/import', req);
-    return res.body;
+    return this.post('/v1/key/import', req);
   }
 
   /**
@@ -194,8 +219,8 @@ export default class Kmd extends ServiceClient {
       address: addr,
       wallet_password: walletPassword,
     };
-    const res = await this.c.post('/v1/key/export', req);
-    return { private_key: Buffer.from(res.body.private_key, 'base64') };
+    const res = await this.post('/v1/key/export', req);
+    return { private_key: base64ToBytes(res.private_key) };
   }
 
   /**
@@ -209,8 +234,7 @@ export default class Kmd extends ServiceClient {
       wallet_handle_token: walletHandle,
       display_mnemonic: false,
     };
-    const res = await this.c.post('/v1/key', req);
-    return res.body;
+    return this.post('/v1/key', req);
   }
 
   /**
@@ -230,8 +254,7 @@ export default class Kmd extends ServiceClient {
       address: addr,
       wallet_password: walletPassword,
     };
-    const res = await this.c.delete('/v1/key', req);
-    return res.body;
+    return this.delete('/v1/key', req);
   }
 
   /**
@@ -243,8 +266,7 @@ export default class Kmd extends ServiceClient {
     const req = {
       wallet_handle_token: walletHandle,
     };
-    const res = await this.c.post('/v1/key/list', req);
-    return res.body;
+    return this.post('/v1/key/list', req);
   }
 
   /**
@@ -259,21 +281,15 @@ export default class Kmd extends ServiceClient {
   async signTransaction(
     walletHandle: string,
     walletPassword: string,
-    transaction: txn.TransactionLike
+    transaction: Transaction
   ) {
-    const tx = txn.instantiateTxnIfNeeded(transaction);
-
     const req = {
       wallet_handle_token: walletHandle,
       wallet_password: walletPassword,
-      transaction: Buffer.from(tx.toByte()).toString('base64'),
+      transaction: bytesToBase64(transaction.toByte()),
     };
-    const res = await this.c.post('/v1/transaction/sign', req);
-
-    if (res.status === 200) {
-      return Buffer.from(res.body.signed_transaction, 'base64');
-    }
-    return res.body;
+    const res = await this.post('/v1/transaction/sign', req);
+    return base64ToBytes(res.signed_transaction);
   }
 
   /**
@@ -289,23 +305,19 @@ export default class Kmd extends ServiceClient {
   async signTransactionWithSpecificPublicKey(
     walletHandle: string,
     walletPassword: string,
-    transaction: txn.TransactionLike,
+    transaction: Transaction,
     publicKey: Uint8Array | string
   ) {
-    const tx = txn.instantiateTxnIfNeeded(transaction);
+    const pk = coerceToBytes(publicKey);
 
     const req = {
       wallet_handle_token: walletHandle,
       wallet_password: walletPassword,
-      transaction: Buffer.from(tx.toByte()).toString('base64'),
-      public_key: Buffer.from(publicKey).toString('base64'),
+      transaction: bytesToBase64(transaction.toByte()),
+      public_key: bytesToBase64(pk),
     };
-    const res = await this.c.post('/v1/transaction/sign', req);
-
-    if (res.status === 200) {
-      return Buffer.from(res.body.signed_transaction, 'base64');
-    }
-    return res.body;
+    const res = await this.post('/v1/transaction/sign', req);
+    return base64ToBytes(res.signed_transaction);
   }
 
   /**
@@ -320,8 +332,7 @@ export default class Kmd extends ServiceClient {
     const req = {
       wallet_handle_token: walletHandle,
     };
-    const res = await this.c.post('/v1/multisig/list', req);
-    return res.body;
+    return this.post('/v1/multisig/list', req);
   }
 
   /**
@@ -346,8 +357,7 @@ export default class Kmd extends ServiceClient {
       threshold,
       pks,
     };
-    const res = await this.c.post('/v1/multisig/import', req);
-    return res.body;
+    return this.post('/v1/multisig/import', req);
   }
 
   /**
@@ -365,8 +375,7 @@ export default class Kmd extends ServiceClient {
       wallet_handle_token: walletHandle,
       address: addr,
     };
-    const res = await this.c.post('/v1/multisig/export', req);
-    return res.body;
+    return this.post('/v1/multisig/export', req);
   }
 
   /**
@@ -384,20 +393,19 @@ export default class Kmd extends ServiceClient {
   async signMultisigTransaction(
     walletHandle: string,
     pw: string,
-    transaction: txn.TransactionLike,
+    transaction: Transaction,
     pk: Uint8Array | string,
     partial: string
   ) {
-    const tx = txn.instantiateTxnIfNeeded(transaction);
+    const pubkey = coerceToBytes(pk);
     const req = {
       wallet_handle_token: walletHandle,
-      transaction: Buffer.from(tx.toByte()).toString('base64'),
-      public_key: Buffer.from(pk).toString('base64'),
+      transaction: bytesToBase64(transaction.toByte()),
+      public_key: bytesToBase64(pubkey),
       partial_multisig: partial,
       wallet_password: pw,
     };
-    const res = await this.c.post('/v1/multisig/sign', req);
-    return res.body;
+    return this.post('/v1/multisig/sign', req);
   }
 
   /**
@@ -418,7 +426,6 @@ export default class Kmd extends ServiceClient {
       address: addr,
       wallet_password: walletPassword,
     };
-    const res = await this.c.delete('/v1/multisig', req);
-    return res.body;
+    return this.delete('/v1/multisig', req);
   }
 }