emissions-api-sdk 1.0.0 → 1.0.1

package/README.md

@@ -23,7 +23,7 @@ yarn install emissions-api-sdk
 ## Quick Start
 
 ```javascript
-import { Client, Location } from 'emissions-api-sdk';
+import { Client, LocationEmission } from 'emissions-api-sdk';
 
 // Initialize client
 await Client.getClient({
@@ -33,7 +33,7 @@ await Client.getClient({
 });
 
 // Calculate emissions
-const result = await Location.calculate({
+const result = await LocationEmission.calculate({
   "location": {
     "country": "USA",
     "stateProvince": "california"
@@ -46,6 +46,37 @@ const result = await Location.calculate({
 });
 ```
 
+## Metadata APIs
+
+The SDK provides Metadata APIs to discover available emission types, geographical areas, and units:
+
+### Get Available Types
+
+```javascript
+import { LocationEmission } from 'emissions-api-sdk';
+
+// Get all available Location emission types
+const types = await LocationEmission.getTypes();
+```
+
+### Get Supported Areas
+
+```javascript
+import { LocationEmission } from 'emissions-api-sdk';
+
+// Get supported geographical areas
+const areas = await LocationEmission.getArea();
+```
+
+### Get Valid Units
+
+```javascript
+import { LocationEmission } from 'emissions-api-sdk';
+
+// Get valid units for a specific emission type
+const units = await LocationEmission.getUnits("electricity");
+```
+
 ## 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.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.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";
@@ -12,6 +12,28 @@ exports.TRANSPORTATION_AND_DISTRIBUTION_API_PATH = "/v3/carbon/transportation-an
 exports.FACTOR_API_PATH = "/v3/carbon/factor";
 exports.FACTOR_SET_API_PATH = "/v3/carbon/factorset";
 exports.SEARCH_API_PATH = "/v3/carbon/factor/search";
+exports.CALCULATION_TYPES = "/v3/carbon/calculation/types";
+exports.LOCATION_TYPES = "/v3/carbon/location/types";
+exports.FUGITIVE_API_TYPES = "/v3/carbon/fugitive/types";
+exports.MOBILE_API_TYPES = "/v3/carbon/mobile/types";
+exports.STATIONARY_API_TYPES = "/v3/carbon/stationary/types";
+exports.FACTOR_API_TYPES = "/v3/carbon/factor/types";
+exports.TRANSPORTATION_AND_DISTRIBUTION_API_TYPES = "/v3/carbon/transportation-and-distribution/types";
+exports.FUGITIVE_API_AREA = "/v3/carbon/fugitive/area";
+exports.GENERAL_API_AREA = "/v3/carbon/calculation/area";
+exports.LOCATION_API_AREA = "/v3/carbon/location/area";
+exports.MOBILE_API_AREA = "/v3/carbon/mobile/area";
+exports.STATIONARY_API_AREA = "/v3/carbon/stationary/area";
+exports.TRANSPORTATION_AND_DISTRIBUTION_API_AREA = "/v3/carbon/transportation-and-distribution/area";
+exports.SEARCH_API_AREA = "/v3/carbon/factor/search/area";
+exports.FACTOR_API_AREA = "/v3/carbon/factor/area";
+exports.FUGITIVE_API_UNITS = "/v3/carbon/fugitive/units";
+exports.LOCATION_API_UNITS = "/v3/carbon/location/units";
+exports.MOBILE_API_UNITS = "/v3/carbon/mobile/units";
+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.GET = "GET";
 exports.POST = "POST";
 exports.CLIENT_SOURCE_HEADER = "X-Client-Source";

package/dist/api/Calculation.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculate = calculate;
+exports.getTypes = getTypes;
+exports.getArea = getArea;
+exports.getUnits = getUnits;
 const Client_1 = require("../Client");
 const Constants_1 = require("../Constants");
 const request_1 = require("../request");
@@ -14,20 +17,20 @@ const request_1 = require("../request");
  *
  * @example
  * const calculationRequest = {
-             "time" : {
-                "date": "2025-01-04"
-            },
-            "location": {
-                "country": "usa",
-                                "stateProvince": "new york"
-            },
-            "activity": {
-                            "type":"Waste Combusted - Steel Cans:Default factor",
-                            "unit": "kg",
-                            "value": 1223123.121
-            },
-            "includeDetails": true
-        };
+    "time" : {
+      "date": "2025-01-04"
+    },
+    "location": {
+      "country": "usa",
+      "stateProvince": "new york"
+    },
+    "activity": {
+      "type":"Waste Combusted - Steel Cans:Default factor",
+      "unit": "kg",
+      "value": 1223123.121
+    },
+    "includeDetails": true
+  };
  * const result = await calculate(calculationRequest);
  */
 async function calculate(payload) {
@@ -39,3 +42,63 @@ async function calculate(payload) {
         data: 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const types = await getTypes();
+ */
+async function getTypes() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.CALCULATION_TYPES;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const areas = await getArea();
+ */
+async function getArea() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.GENERAL_API_AREA;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * Retrieves available units for a specific calculation type.
+ *
+ * @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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * // Get units for the "Natural Gas - Scope 3:AAA" emission calculation type with subtype
+ * const units = await getUnits("Natural Gas - Scope 3:AAA");
+
+ * // Get units for the "HFC-263fb" emission calculation type without subtype
+ * const units = await getUnits("HFC-263fb");
+ */
+async function getUnits(type) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.GENERAL_API_UNITS;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url,
+        params: { type }
+    });
+}

package/dist/api/Factor.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retrieveFactor = retrieveFactor;
 exports.search = search;
+exports.getTypes = getTypes;
+exports.getSearchArea = getSearchArea;
+exports.getArea = getArea;
+exports.getUnits = getUnits;
 const Client_1 = require("../Client");
 const Constants_1 = require("../Constants");
 const request_1 = require("../request");
@@ -15,27 +19,26 @@ const request_1 = require("../request");
  *
  * @example
  * const factorRequest = {
-    
     "activity": {
-         "factorId": 12345
+      "factorId": 12345
     }
   };
   
-  or
+  OR
 
   const factorRequest = {
-             "time" : {
-                "date": "2025-01-04"
-            },
-            "location": {
-                "country": "usa",
-                                "stateProvince": "new york"
-            },
-            "activity": {
-                            "type":"natural gas"
-            },
-            "includeDetails": true
-        };
+    "time" : {
+      "date": "2025-01-04"
+    },
+    "location": {
+      "country": "usa",
+      "stateProvince": "new york"
+    },
+    "activity": {
+      "type":"natural gas"
+    },
+    "includeDetails": true
+  };
  * const factor = await retrieveFactor(factorRequest);
  */
 async function retrieveFactor(payload) {
@@ -62,7 +65,7 @@ async function retrieveFactor(payload) {
     },
     "activity": {
       "search" : "travel"},
-  "location": {
+    "location": {
       "country": "USA"
     }
   };
@@ -77,3 +80,81 @@ async function search(payload) {
         data: 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const types = await getTypes();
+ */
+async function getTypes() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.FACTOR_API_TYPES;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const areas = await getArea();
+ */
+async function getSearchArea() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.SEARCH_API_AREA;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const areas = await getArea();
+ */
+async function getArea() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.FACTOR_API_AREA;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * Retrieves available units for a specific emission factor type.
+ *
+ * @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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * // Get units for the "Natural Gas - Scope 3:AAA" emission factor type with subtype
+ * const units = await getUnits("Natural Gas - Scope 3:AAA");
+
+ * // Get units for the "HFC-263fb" emission factor type without subtype
+ * const units = await getUnits("HFC-263fb");
+ */
+async function getUnits(type) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.FACTOR_API_UNITS;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url,
+        params: { type }
+    });
+}

package/dist/api/Fugitive.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculate = calculate;
+exports.getTypes = getTypes;
+exports.getArea = getArea;
+exports.getUnits = getUnits;
 const Client_1 = require("../Client");
 const Constants_1 = require("../Constants");
 const request_1 = require("../request");
@@ -14,18 +17,18 @@ const request_1 = require("../request");
  *
  * @example
  * const request = {
-      "time": {
-        "date": "2025-01-04"
-      },
-      "location": {
-        "country": "usa"
-      },
-      "activity": {
-        "type": "R134A",
-        "value": 150,
-        "unit": "kg"
-      },
-      "includeDetails": false
+    "time": {
+      "date": "2025-01-04"
+    },
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "type": "R134A",
+      "value": 150,
+      "unit": "kg"
+    },
+    "includeDetails": false
   };
  * const result = await calculate(request);
  */
@@ -38,3 +41,63 @@ async function calculate(payload) {
         data: 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const types = await getTypes();
+ */
+async function getTypes() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.FUGITIVE_API_TYPES;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const areas = await getArea();
+ */
+async function getArea() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.FUGITIVE_API_AREA;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * Retrieves available units for a specific fugitive emission type.
+ *
+ * @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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * // Get units for the "Natural Gas - Scope 3:AAA" emission fugitive type with subtype
+ * const units = await getUnits("Natural Gas - Scope 3:AAA");
+
+ * // Get units for the "R-426A" emission fugitive type without subtype
+ * const units = await getUnits("R-426A");
+ */
+async function getUnits(type) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.FUGITIVE_API_UNITS;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url,
+        params: { type }
+    });
+}

package/dist/api/Location.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculate = calculate;
+exports.getTypes = getTypes;
+exports.getArea = getArea;
+exports.getUnits = getUnits;
 const Client_1 = require("../Client");
 const Constants_1 = require("../Constants");
 const request_1 = require("../request");
@@ -14,20 +17,20 @@ const request_1 = require("../request");
  *
  * @example
  * const calculationRequest = {
-             "time" : {
-                "date": "2025-01-04"
-            },
-            "location": {
-                "country": "usa",
-                                "stateProvince": "new york"
-            },
-            "activity": {
-                            "type":"electricity",
-                            "unit": "kwh",
-                            "value": 14123143
-            },
-            "includeDetails": true
-        };
+    "time" : {
+      "date": "2025-01-04"
+    },
+    "location": {
+      "country": "usa",
+      "stateProvince": "new york"
+    },
+    "activity": {
+      "type":"electricity",
+      "unit": "kwh",
+      "value": 14123143
+    },
+    "includeDetails": true
+  };
  * const result = await calculate(calculationRequest);
  */
 async function calculate(payload) {
@@ -39,3 +42,61 @@ async function calculate(payload) {
         data: 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ *
+ * const types = await getTypes();
+ */
+async function getTypes() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.LOCATION_TYPES;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const areas = await getArea();
+ */
+async function getArea() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.LOCATION_API_AREA;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * Retrieves available units for a specific location-based calculation type.
+ *
+ * @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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * // Get units for the "electricity" location type
+ * const units = await getUnits("electricity");
+ */
+async function getUnits(type) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.LOCATION_API_UNITS;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url,
+        params: { type }
+    });
+}

package/dist/api/Mobile.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculate = calculate;
+exports.getTypes = getTypes;
+exports.getArea = getArea;
+exports.getUnits = getUnits;
 const request_1 = require("../request");
 const Constants_1 = require("../Constants");
 const Client_1 = require("../Client");
@@ -39,3 +42,66 @@ async function calculate(payload) {
         data: 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
+ * @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();
+    const url = client.getDomain() + Constants_1.MOBILE_API_TYPES;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const areas = await getArea();
+ */
+async function getArea() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.MOBILE_API_AREA;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url
+    });
+}
+/**
+ * Retrieves available units for a specific mobile emission type.
+ *
+ * @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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * Get units for the "Cars:B20:(NE)" emission mobile type with subtype
+ * const units = await getUnits("Cars:B20:(NE)");
+
+ * Get units for the "Cars by Size - Large Car - Hybrid" emission mobile type without subtype
+ * const units = await getUnits("Cars by Size - Large Car - Hybrid");
+ */
+async function getUnits(type) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.MOBILE_API_UNITS;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url,
+        params: { type }
+    });
+}