emissions-api-sdk 1.0.0 → 1.0.1

package/sphinx-build/source/reference.rst

@@ -0,0 +1,129 @@
+=========
+Reference
+=========
+
+
+.. js:autoclass:: Client
+   :members: 
+
+.. js:autofunction:: request.makeApiRequest
+
+.. js:autofunction:: utils.findExpiryTime
+
+API
+===
+
+.. js:autofunction:: Factor.retrieveFactor
+
+.. js:autofunction:: Fugitive.calculate
+
+.. js:autofunction:: Calculation.calculate
+
+.. js:autofunction:: Location.calculate
+
+.. js:autofunction:: Mobile.calculate
+
+.. js:autofunction:: Stationary.calculate
+
+.. js:autofunction:: TransportationAndDistribution.calculate
+
+Metadata APIs
+===========
+
+getTypes
+--------
+
+.. js:autofunction:: Factor.getTypes
+
+.. js:autofunction:: Calculation.getTypes
+
+.. js:autofunction:: Location.getTypes
+
+.. js:autofunction:: Mobile.getTypes
+
+.. js:autofunction:: Stationary.getTypes
+
+.. js:autofunction:: TransportationAndDistribution.getTypes
+
+.. js:autofunction:: Fugitive.getTypes
+
+getArea
+-------
+
+.. js:autofunction:: Factor.getArea
+
+.. js:autofunction:: Factor.getSearchArea
+
+.. js:autofunction:: Calculation.getArea
+
+.. js:autofunction:: Location.getArea
+
+.. js:autofunction:: Mobile.getArea
+
+.. js:autofunction:: Stationary.getArea
+
+.. js:autofunction:: TransportationAndDistribution.getArea
+
+.. js:autofunction:: Fugitive.getArea
+
+getUnits
+--------
+
+.. js:autofunction:: Factor.getUnits
+
+.. js:autofunction:: Calculation.getUnits
+
+.. js:autofunction:: Location.getUnits
+
+.. js:autofunction:: Mobile.getUnits
+
+.. js:autofunction:: Stationary.getUnits
+
+.. js:autofunction:: TransportationAndDistribution.getUnits
+
+.. js:autofunction:: Fugitive.getUnits
+
+Interfaces
+==========
+
+.. js:autoclass:: Api.LocationRequestWithoutFactorId
+
+.. js:autoclass:: Api.LocationRequestWithFactorId
+
+.. js:autoclass:: Api.CommonRequestWithoutFactorId
+
+.. js:autoclass:: Api.CommonRequestWithFactorId
+
+.. js:autoclass:: Api.GenericCalculationRequestWithoutFactorId
+
+.. js:autoclass:: Api.GenericCalculationRequestWithFactorId
+
+.. js:autoclass:: Api.FactorRequestWithoutFactorId
+
+.. js:autoclass:: Api.FactorRequestWithFactorId
+
+.. js:autoclass:: Api.SearchRequest
+
+.. js:autoclass:: common.Location
+
+.. js:autoclass:: common.Time
+
+.. js:autoclass:: common.Activity
+
+.. js:autoclass:: common.ActivityWithFactorId
+
+.. js:autoclass:: common.CombinedUnitsActivity
+
+.. js:autoclass:: common.CombinedUnitsActivityWithFactorId
+
+.. js:autoclass:: common.FactorActivity
+
+.. js:autoclass:: common.FactorActivityWithFactorId
+
+.. js:autoclass:: common.SearchActivity
+
+.. js:autoclass:: common.Pagination
+
+.. js:autoclass:: Config.RequestConfig
+
+.. js:autoclass:: Config.ClientConfig

package/sphinx-build/source/sdk.rst

@@ -0,0 +1,13 @@
+===
+SDK
+===
+
+The IBM Envizi - Emissions API Node.js SDK provides a structured approach to interact with the Emissions API. This section covers the key components and usage patterns.
+
+.. toctree::
+   :maxdepth: 2
+
+   client
+   authentication
+
+.. Made with Bob

package/src/Constants.ts

@@ -9,6 +9,32 @@ export const TRANSPORTATION_AND_DISTRIBUTION_API_PATH = "/v3/carbon/transportati
 export const FACTOR_API_PATH = "/v3/carbon/factor";
 export const FACTOR_SET_API_PATH = "/v3/carbon/factorset";
 export const SEARCH_API_PATH = "/v3/carbon/factor/search";
+
+export const CALCULATION_TYPES = "/v3/carbon/calculation/types";
+export const LOCATION_TYPES = "/v3/carbon/location/types";
+export const FUGITIVE_API_TYPES = "/v3/carbon/fugitive/types";
+export const MOBILE_API_TYPES = "/v3/carbon/mobile/types";
+export const STATIONARY_API_TYPES = "/v3/carbon/stationary/types";
+export const FACTOR_API_TYPES = "/v3/carbon/factor/types";
+export const TRANSPORTATION_AND_DISTRIBUTION_API_TYPES = "/v3/carbon/transportation-and-distribution/types";
+
+export const FUGITIVE_API_AREA = "/v3/carbon/fugitive/area";
+export const GENERAL_API_AREA = "/v3/carbon/calculation/area";
+export const LOCATION_API_AREA = "/v3/carbon/location/area";
+export const MOBILE_API_AREA = "/v3/carbon/mobile/area";
+export const STATIONARY_API_AREA = "/v3/carbon/stationary/area";
+export const TRANSPORTATION_AND_DISTRIBUTION_API_AREA = "/v3/carbon/transportation-and-distribution/area";
+export const SEARCH_API_AREA = "/v3/carbon/factor/search/area";
+export const FACTOR_API_AREA = "/v3/carbon/factor/area";
+
+export const FUGITIVE_API_UNITS = "/v3/carbon/fugitive/units";
+export const LOCATION_API_UNITS = "/v3/carbon/location/units";
+export const MOBILE_API_UNITS = "/v3/carbon/mobile/units";
+export const STATIONARY_API_UNITS = "/v3/carbon/stationary/units";
+export const GENERAL_API_UNITS = "/v3/carbon/calculation/units";
+export const FACTOR_API_UNITS = "/v3/carbon/factor/units";
+export const TRANSPORTATION_AND_DISTRIBUTION_API_UNITS = "/v3/carbon/transportation-and-distribution/units";
+
 export const GET = "GET";
 export const POST = "POST";
 export const CLIENT_SOURCE_HEADER = "X-Client-Source";

package/src/api/Calculation.ts

@@ -1,5 +1,5 @@
 import { Client } from "../Client";
-import { GENERIC_CALCULATION_API_PATH, POST } from "../Constants";
+import { GENERIC_CALCULATION_API_PATH,CALCULATION_TYPES, POST, GET, GENERAL_API_AREA, GENERAL_API_UNITS } from "../Constants";
 import { CalculationRequest } from "../interfaces/Api";
 import { makeApiRequest } from "../request";
 
@@ -14,20 +14,20 @@ import { makeApiRequest } from "../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);
  */
 export async function calculate(
@@ -42,3 +42,72 @@ export async function calculate(
     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();
+ */
+export async function getTypes(): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + CALCULATION_TYPES;
+
+  return makeApiRequest<string>({
+    method: 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();
+ */
+export async function getArea(): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + GENERAL_API_AREA;
+
+  return makeApiRequest<string>({
+    method: 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");
+ */
+export async function getUnits(
+  type: string
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + GENERAL_API_UNITS;
+
+  return makeApiRequest<string>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/api/Factor.ts

@@ -1,5 +1,5 @@
 import { Client } from "../Client";
-import { FACTOR_API_PATH, POST, SEARCH_API_PATH } from "../Constants";
+import { FACTOR_API_AREA, FACTOR_API_PATH, FACTOR_API_TYPES, FACTOR_API_UNITS, GET, POST, SEARCH_API_AREA, SEARCH_API_PATH } from "../Constants";
 import { FactorRequest, SearchRequest } from "../interfaces/Api";
 import { makeApiRequest } from "../request";
 
@@ -13,27 +13,26 @@ import { makeApiRequest } from "../request";
  * 
  * @example
  * const factorRequest = {
-	
-	"activity": {
-		 "factorId": 12345
-	}
+    "activity": {
+      "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);
  */
 
@@ -66,7 +65,7 @@ export async function retrieveFactor(
     },
     "activity": {
       "search" : "travel"},
-  "location": {
+    "location": {
       "country": "USA"
     }
   };
@@ -84,3 +83,93 @@ export async function search(
     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();
+ */
+export async function getTypes(
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FACTOR_API_TYPES;
+
+  return makeApiRequest<string>({
+    method: 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();
+ */
+export async function getSearchArea(
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + SEARCH_API_AREA;
+
+  return makeApiRequest<string>({
+    method: 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();
+ */
+export async function getArea(): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FACTOR_API_AREA;
+
+  return makeApiRequest<string>({
+    method: 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");
+ */
+export async function getUnits(
+  type : string
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FACTOR_API_UNITS;
+
+  return makeApiRequest<string>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/api/Fugitive.ts

@@ -1,5 +1,5 @@
 import { Client } from "../Client";
-import { FUGITIVE_API_PATH, POST } from "../Constants";
+import { FUGITIVE_API_AREA, FUGITIVE_API_PATH, FUGITIVE_API_TYPES, FUGITIVE_API_UNITS, GET, POST } from "../Constants";
 import { CommonRequest } from "../interfaces/Api";
 import { makeApiRequest } from "../request";
 
@@ -13,18 +13,18 @@ import { makeApiRequest } from "../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);
  */
@@ -41,3 +41,73 @@ export async function calculate(
     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();
+ */
+export async function getTypes(
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FUGITIVE_API_TYPES;
+
+  return makeApiRequest<string>({
+    method: 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();
+ */
+export async function getArea(
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FUGITIVE_API_AREA;
+
+  return makeApiRequest<string>({
+    method: 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");
+ */
+export async function getUnits(
+  type : string
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FUGITIVE_API_UNITS;
+
+  return makeApiRequest<string>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/api/Location.ts

@@ -1,5 +1,5 @@
 import { Client } from "../Client";
-import { LOCATION_API_PATH, POST } from "../Constants";
+import { GET, LOCATION_API_AREA, LOCATION_API_PATH, LOCATION_API_UNITS, LOCATION_TYPES, POST } from "../Constants";
 import { LocationRequest } from "../interfaces/Api";
 import { makeApiRequest } from "../request";
 
@@ -13,20 +13,20 @@ import { makeApiRequest } from "../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);
  */
 export async function calculate(
@@ -41,3 +41,72 @@ export async function calculate(
     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();
+ */
+export async function getTypes(
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + LOCATION_TYPES;
+
+  return makeApiRequest<string>({
+    method: 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();
+ */
+export async function getArea(
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + LOCATION_API_AREA;
+
+  return makeApiRequest<string>({
+    method: 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");
+ */
+export async function getUnits(
+  type : string
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + LOCATION_API_UNITS;
+
+  return makeApiRequest<string>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}