emissions-api-sdk 1.0.1 → 1.0.3

package/README.md

@@ -77,6 +77,15 @@ import { LocationEmission } from 'emissions-api-sdk';
 const units = await LocationEmission.getUnits("electricity");
 ```
 
+### Get Organization Usage
+```javascript
+import { Usage } from 'emissions-api-sdk';
+
+// Retrieves current billing period or historical usage data for the Organization 
+// History Flag to retrieve current billing or historical usage data.
+const units = await Usage.getUsage(true);
+```
+
 ## Authentication
 
 The SDK supports two authentication methods:

package/dist/Constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLIENT_SOURCE_SDK = exports.CLIENT_SOURCE_EXCEL = exports.CLIENT_SOURCE_HEADER = exports.POST = exports.GET = exports.TRANSPORTATION_AND_DISTRIBUTION_API_UNITS = exports.FACTOR_API_UNITS = exports.GENERAL_API_UNITS = exports.STATIONARY_API_UNITS = exports.MOBILE_API_UNITS = exports.LOCATION_API_UNITS = exports.FUGITIVE_API_UNITS = exports.FACTOR_API_AREA = exports.SEARCH_API_AREA = exports.TRANSPORTATION_AND_DISTRIBUTION_API_AREA = exports.STATIONARY_API_AREA = exports.MOBILE_API_AREA = exports.LOCATION_API_AREA = exports.GENERAL_API_AREA = exports.FUGITIVE_API_AREA = exports.TRANSPORTATION_AND_DISTRIBUTION_API_TYPES = exports.FACTOR_API_TYPES = exports.STATIONARY_API_TYPES = exports.MOBILE_API_TYPES = exports.FUGITIVE_API_TYPES = exports.LOCATION_TYPES = exports.CALCULATION_TYPES = exports.SEARCH_API_PATH = exports.FACTOR_SET_API_PATH = exports.FACTOR_API_PATH = exports.TRANSPORTATION_AND_DISTRIBUTION_API_PATH = exports.GENERIC_CALCULATION_API_PATH = exports.STATIONARY_API_PATH = exports.FUGITIVE_API_PATH = exports.LOCATION_API_PATH = exports.MOBILE_API_PATH = exports.TOKEN_GENERATION_API = exports.API_DOMAIN = void 0;
+exports.CLIENT_SOURCE_SDK = exports.CLIENT_SOURCE_EXCEL = exports.CLIENT_SOURCE_HEADER = exports.POST = exports.GET = exports.USAGE_API = exports.TRANSPORTATION_AND_DISTRIBUTION_API_UNITS = exports.FACTOR_API_UNITS = exports.GENERAL_API_UNITS = exports.STATIONARY_API_UNITS = exports.MOBILE_API_UNITS = exports.LOCATION_API_UNITS = exports.FUGITIVE_API_UNITS = exports.FACTOR_API_AREA = exports.SEARCH_API_AREA = exports.TRANSPORTATION_AND_DISTRIBUTION_API_AREA = exports.STATIONARY_API_AREA = exports.MOBILE_API_AREA = exports.LOCATION_API_AREA = exports.GENERAL_API_AREA = exports.FUGITIVE_API_AREA = exports.TRANSPORTATION_AND_DISTRIBUTION_API_TYPES = exports.FACTOR_API_TYPES = exports.STATIONARY_API_TYPES = exports.MOBILE_API_TYPES = exports.FUGITIVE_API_TYPES = exports.LOCATION_TYPES = exports.CALCULATION_TYPES = exports.SEARCH_API_PATH = exports.FACTOR_SET_API_PATH = exports.FACTOR_API_PATH = exports.TRANSPORTATION_AND_DISTRIBUTION_API_PATH = exports.GENERIC_CALCULATION_API_PATH = exports.STATIONARY_API_PATH = exports.FUGITIVE_API_PATH = exports.LOCATION_API_PATH = exports.MOBILE_API_PATH = exports.TOKEN_GENERATION_API = exports.API_DOMAIN = void 0;
 exports.API_DOMAIN = "https://api.ibm.com/ghgemissions/run";
 exports.TOKEN_GENERATION_API = "https://api.ibm.com/saascore/run/authentication-retrieve/api-key";
 exports.MOBILE_API_PATH = "/v3/carbon/mobile";
@@ -34,6 +34,7 @@ exports.STATIONARY_API_UNITS = "/v3/carbon/stationary/units";
 exports.GENERAL_API_UNITS = "/v3/carbon/calculation/units";
 exports.FACTOR_API_UNITS = "/v3/carbon/factor/units";
 exports.TRANSPORTATION_AND_DISTRIBUTION_API_UNITS = "/v3/carbon/transportation-and-distribution/units";
+exports.USAGE_API = "/v3/carbon/usage";
 exports.GET = "GET";
 exports.POST = "POST";
 exports.CLIENT_SOURCE_HEADER = "X-Client-Source";

package/dist/api/Calculation.js

@@ -12,7 +12,7 @@ const request_1 = require("../request");
  *
  * @export
  * @param {CalculationRequest} payload - The calculation request data to be sent to the API
- * @return {Promise<string>} A promise that resolves to the calculation result string returned by the API
+ * @return {Promise<EmissionResponse | EmissionResponseWithDetails>} A promise that resolves to the emission calculation result. Returns EmissionResponseWithDetails if includeDetails is true, otherwise EmissionResponse
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -46,7 +46,7 @@ async function calculate(payload) {
  * Retrieves available calculation types by making a GET request to the calculation types API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the available calculation types
+ * @return {Promise<TypeResponse>} A promise that resolves to a TypeResponse containing the available calculation types
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -64,7 +64,7 @@ async function getTypes() {
  * Retrieves information about geographical areas supported by the calculation API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @return {Promise<AreaResponse>} A promise that resolves to an AreaResponse containing the supported geographical areas
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -83,7 +83,7 @@ async function getArea() {
  *
  * @export
  * @param {string} type - The calculation type to get units for
- * @return {Promise<string>} A promise that resolves to a string containing the available units
+ * @return {Promise<UnitResponse>} A promise that resolves to a UnitResponse containing the available units
  * @throws {Error} May throw an error if the API request fails
  *
  * @example

package/dist/api/Factor.js

@@ -14,7 +14,7 @@ const request_1 = require("../request");
  *
  * @export
  * @param {FactorRequest} payload - The factor request data to be sent to the API
- * @return {Promise<string>} A promise that resolves to the factor string returned by the API
+ * @return {Promise<FactorResponse>} A promise that resolves to the FactorResponse returned by the API
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -55,7 +55,7 @@ async function retrieveFactor(payload) {
  *
  * @export
  * @param {SearchRequest} payload - The search request data to be sent to the API
- * @return {Promise<string>} A promise that resolves to the search results string returned by the API
+ * @return {Promise<SearchResponse>} A promise that resolves to the search results returned by the API
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -84,7 +84,7 @@ async function search(payload) {
  * Retrieves available emission factor types by making a GET request to the API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the available emission factor types
+ * @return {Promise<TypeResponse>} A promise that resolves to a TypeResponse containing the available emission factor types
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -102,11 +102,11 @@ async function getTypes() {
  * Retrieves information about geographical areas supported by the factor search API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @return {Promise<AreaResponse>} A promise that resolves to an AreaResponse containing the supported geographical areas
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
- * const areas = await getArea();
+ * const areas = await getSearchArea();
  */
 async function getSearchArea() {
     const client = Client_1.Client.getInstance();
@@ -120,7 +120,7 @@ async function getSearchArea() {
  * Retrieves information about geographical areas supported by the factor API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @return {Promise<AreaResponse>} A promise that resolves to an AreaResponse containing the supported geographical areas
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -139,7 +139,7 @@ async function getArea() {
  *
  * @export
  * @param {string} type - The emission factor type to get units for (e.g., "Natural Gas - Scope 3:AAA")
- * @return {Promise<string>} A promise that resolves to a string containing the available units
+ * @return {Promise<UnitResponse>} A promise that resolves to a UnitResponse containing the available units
  * @throws {Error} May throw an error if the API request fails
  *
  * @example

package/dist/api/FactorSets.js

@@ -8,7 +8,7 @@ const request_1 = require("../request");
  * Retrieves factor sets by making a GET request to the factor set API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to the factor sets string returned by the API
+ * @return {Promise<FactorSetResponse>} A promise that resolves to the  FactorSetResponse returned by the API
  * @throws {Error} May throw an error if the API request fails
  *
  * @example

package/dist/api/Fugitive.js

@@ -12,7 +12,7 @@ const request_1 = require("../request");
  *
  * @export
  * @param {CommonRequest} payload - The request data to be sent to the API
- * @return {Promise<string>} A promise that resolves to the calculation result string returned by the API
+ * @return {Promise<EmissionResponse | EmissionResponseWithDetails>} A promise that resolves to the emission calculation result. Returns EmissionResponseWithDetails if includeDetails is true, otherwise EmissionResponse
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -45,7 +45,7 @@ async function calculate(payload) {
  * Retrieves available fugitive emission calculation types by making a GET request to the API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the available fugitive emission types
+ * @return {Promise<TypeResponse>} A promise that resolves to a TypeResponse containing the available fugitive emission types
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -63,7 +63,7 @@ async function getTypes() {
  * Retrieves information about geographical areas supported by the fugitive emissions API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @return {Promise<AreaResponse>} A promise that resolves to an AreaResponse containing the supported geographical areas
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -82,7 +82,7 @@ async function getArea() {
  *
  * @export
  * @param {string} type - The fugitive emission type to get units for (e.g., "R134A")
- * @return {Promise<string>} A promise that resolves to a string containing the available units
+ * @return {Promise<UnitResponse>} A promise that resolves to a UnitResponse containing the available units
  * @throws {Error} May throw an error if the API request fails
  *
  * @example

package/dist/api/Location.js

@@ -12,7 +12,7 @@ const request_1 = require("../request");
  *
  * @export
  * @param {LocationRequest} payload - The location request data to be sent to the API
- * @return {Promise<string>} A promise that resolves to the purchased energy emission result string returned by the API
+ * @return {Promise<EmissionResponse | EmissionResponseWithDetails>} A promise that resolves to the emission calculation result. Returns EmissionResponseWithDetails if includeDetails is true, otherwise EmissionResponse
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -46,7 +46,7 @@ async function calculate(payload) {
  * Retrieves available location-based calculation types by making a GET request to the location types API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the available location-based calculation types
+ * @return {Promise<TypeResponse>} A promise that resolves to a TypeResponse containing the available location-based calculation types
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -65,7 +65,7 @@ async function getTypes() {
  * Retrieves information about geographical areas supported by the location-based calculation API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @return {Promise<AreaResponse>} A promise that resolves to an AreaResponse containing the supported geographical areas
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -84,7 +84,7 @@ async function getArea() {
  *
  * @export
  * @param {string} type - The location-based calculation type to get units for (e.g., "electricity")
- * @return {Promise<string>} A promise that resolves to a string containing the available units
+ * @return {Promise<UnitResponse>} A promise that resolves to a UnitResponse containing the available units
  * @throws {Error} May throw an error if the API request fails
  *
  * @example

package/dist/api/Mobile.js

@@ -12,7 +12,7 @@ const Client_1 = require("../Client");
  *
  * @export
  * @param {CommonRequest} payload - The request data to be sent to the mobile API
- * @return {Promise<string>} A promise that resolves to the calculation result string returned by the API
+ * @return {Promise<EmissionResponse | EmissionResponseWithDetails>} A promise that resolves to the emission calculation result. Returns EmissionResponseWithDetails if includeDetails is true, otherwise EmissionResponse
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -46,14 +46,12 @@ async function calculate(payload) {
  * Retrieves available mobile emission calculation types by making a GET request to the API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the available mobile emission types
+ * @return {Promise<TypeResponse>} A promise that resolves to a TypeResponse containing the available mobile emission types
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
  * // Get all available mobile emission types
  * const types = await getTypes();
- * const typesData = JSON.parse(types);
- * console.log("Available mobile emission types:", typesData);
  */
 async function getTypes() {
     const client = Client_1.Client.getInstance();
@@ -67,7 +65,7 @@ async function getTypes() {
  * Retrieves information about geographical areas supported by the mobile emissions API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @return {Promise<AreaResponse>} A promise that resolves to an AreaResponse containing the supported geographical areas
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -86,7 +84,7 @@ async function getArea() {
  *
  * @export
  * @param {string} type - The mobile emission type to get units for (e.g., "Diesel Fuel")
- * @return {Promise<string>} A promise that resolves to a string containing the available units
+ * @return {Promise<UnitResponse>} A promise that resolves to a UnitResponse containing the available units
  * @throws {Error} May throw an error if the API request fails
  *
  * @example

package/dist/api/Stationary.js

@@ -12,7 +12,7 @@ const request_1 = require("../request");
  *
  * @export
  * @param {CommonRequest} payload - The request data to be sent to the stationary API
- * @return {Promise<string>} A promise that resolves to the calculation result string returned by the API
+ * @return {Promise<EmissionResponse | EmissionResponseWithDetails>} A promise that resolves to the emission calculation result. Returns EmissionResponseWithDetails if includeDetails is true, otherwise EmissionResponse
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -46,7 +46,7 @@ async function calculate(payload) {
  * Retrieves available stationary emission calculation types by making a GET request to the API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the available stationary emission types
+ * @return {Promise<TypeResponse>} A promise that resolves to a TypeResponse containing the available stationary emission types
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -64,7 +64,7 @@ async function getTypes() {
  * Retrieves information about geographical areas supported by the stationary emissions API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @return {Promise<AreaResponse>} A promise that resolves to an AreaResponse containing the supported geographical areas
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -83,7 +83,7 @@ async function getArea() {
  *
  * @export
  * @param {string} type - The stationary emission type to get units for (e.g., "Coal - Lignite")
- * @return {Promise<string>} A promise that resolves to a string containing the available units
+ * @return {Promise<UnitResponse>} A promise that resolves to a UnitResponse containing the available units
  * @throws {Error} May throw an error if the API request fails
  *
  * @example

package/dist/api/TransportationAndDistribution.js

@@ -8,11 +8,11 @@ const Client_1 = require("../Client");
 const Constants_1 = require("../Constants");
 const request_1 = require("../request");
 /**
- * Performs Scope 2 transportation and distribution emission calculations by making a POST request to the transportation and distribution API endpoint.
+ * Performs Scope 3 transportation and distribution emission calculations by making a POST request to the transportation and distribution API endpoint.
  *
  * @export
  * @param {CalculationRequest} payload - The calculation request data for transportation and distribution operations
- * @return {Promise<string>} A promise that resolves to the calculation result string returned by the API
+ * @return {Promise<EmissionResponse | EmissionResponseWithDetails>} A promise that resolves to the emission calculation result. Returns EmissionResponseWithDetails if includeDetails is true, otherwise EmissionResponse
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -45,7 +45,7 @@ async function calculate(payload) {
  * Retrieves available transportation and distribution calculation types by making a GET request to the API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the available transportation and distribution calculation types
+ * @return {Promise<TypeResponse>} A promise that resolves to a TypeResponse containing the available transportation and distribution calculation types
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -63,7 +63,7 @@ async function getTypes() {
  * Retrieves information about geographical areas supported by the transportation and distribution API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @return {Promise<AreaResponse>} A promise that resolves to an AreaResponse containing the supported geographical areas
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
@@ -82,7 +82,7 @@ async function getArea() {
  *
  * @export
  * @param {string} type - The transportation and distribution calculation type to get units for (e.g., "Freight - Cargo Ship")
- * @return {Promise<string>} A promise that resolves to a string containing the available units
+ * @return {Promise<UnitResponse>} A promise that resolves to a UnitResponse containing the available units
  * @throws {Error} May throw an error if the API request fails
  *
  * @example

package/dist/api/Usage.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUsage = getUsage;
+const Client_1 = require("../Client");
+const Constants_1 = require("../Constants");
+const request_1 = require("../request");
+/**
+ * Retrieves current billing period or historical usage data for the user by making a GET request to the API endpoint.
+ *
+ * @export
+ * @param {boolean} history - Flag to retrieve current billing or historical usage data.
+ * @return {Promise<UsageResponse>} A promise that resolves to a UsageResponse containing the organization's usage data
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const usage = await getUsage();
+ */
+async function getUsage(history = false) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.USAGE_API;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url,
+        params: { history }
+    });
+}