emissions-api-sdk 1.0.0 → 1.0.2

package/src/api/Calculation.ts

@@ -1,44 +1,118 @@
 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 { AreaResponse } from "../interfaces/response/AreaResponse";
+import { EmissionResponse } from "../interfaces/response/EmissionResponse";
+import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResponseWithDetails";
+import { TypeResponse } from "../interfaces/response/TypeResponse";
+import { UnitResponse } from "../interfaces/response/UnitResponse";
 import { makeApiRequest } from "../request";
 
 
 /**
  * Performs emission calculations by making a POST request to the generic calculation API endpoint.
- * 
+ *
  * @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
  * 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(
   payload: CalculationRequest
-): Promise<string> {
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
   const client = Client.getInstance();
   const url = client.getDomain() + GENERIC_CALCULATION_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
     method: POST,
     url,
     data: payload,
   });
 }
+
+
+/**
+ * Retrieves available calculation types by making a GET request to the calculation types API endpoint.
+ *
+ * @export
+ * @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
+ * const types = await getTypes();
+ */
+export async function getTypes(): Promise<TypeResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + CALCULATION_TYPES;
+
+  return makeApiRequest<TypeResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves information about geographical areas supported by the calculation API.
+ *
+ * @export
+ * @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();
+ */
+export async function getArea(): Promise<AreaResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + GENERAL_API_AREA;
+
+  return makeApiRequest<AreaResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves available units for a specific calculation type.
+ *
+ * @export
+ * @param {string} type - The calculation type to get units for
+ * @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
+ * // 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<UnitResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + GENERAL_API_UNITS;
+
+  return makeApiRequest<UnitResponse>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/api/Factor.ts

@@ -1,6 +1,11 @@
 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 { AreaResponse } from "../interfaces/response/AreaResponse";
+import { FactorResponse } from "../interfaces/response/FactorResponse";
+import { SearchResponse } from "../interfaces/response/SearchResponse";
+import { TypeResponse } from "../interfaces/response/TypeResponse";
+import { UnitResponse } from "../interfaces/response/UnitResponse";
 import { makeApiRequest } from "../request";
 
 /**
@@ -8,42 +13,41 @@ import { makeApiRequest } from "../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
  * 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);
  */
 
 export async function retrieveFactor(
   payload: FactorRequest
-): Promise<string> {
+): Promise<FactorResponse> {
   const client = Client.getInstance();
   const url =  client.getDomain() + FACTOR_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<FactorResponse>({
     method: POST,
     url,
     data: payload,
@@ -53,20 +57,20 @@ export async function retrieveFactor(
 
 /**
  * Performs a search operation by making a POST request to the search API endpoint.
- * 
+ *
  * @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
- * const searchRequest = { 
+ * const searchRequest = {
     "time":{
       "date": "2020-06-10"
     },
     "activity": {
       "search" : "travel"},
-  "location": {
+    "location": {
       "country": "USA"
     }
   };
@@ -74,13 +78,103 @@ export async function retrieveFactor(
  */
 export async function search(
   payload: SearchRequest
-): Promise<string> {
+): Promise<SearchResponse> {
   const client = Client.getInstance();
   const url = client.getDomain() + SEARCH_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<SearchResponse>({
     method: POST,
     url,
     data: payload,
   });
 }
+
+/**
+ * Retrieves available emission factor types by making a GET request to the API endpoint.
+ *
+ * @export
+ * @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
+ * const types = await getTypes();
+ */
+export async function getTypes(
+): Promise<TypeResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FACTOR_API_TYPES;
+
+  return makeApiRequest<TypeResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves information about geographical areas supported by the factor search API.
+ *
+ * @export
+ * @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 getSearchArea();
+ */
+export async function getSearchArea(
+): Promise<AreaResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + SEARCH_API_AREA;
+
+  return makeApiRequest<AreaResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves information about geographical areas supported by the factor API.
+ *
+ * @export
+ * @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();
+ */
+export async function getArea(): Promise<AreaResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FACTOR_API_AREA;
+
+  return makeApiRequest<AreaResponse>({
+    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<UnitResponse>} A promise that resolves to a UnitResponse 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<UnitResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FACTOR_API_UNITS;
+
+  return makeApiRequest<UnitResponse>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/api/FactorSets.ts

@@ -1,23 +1,24 @@
 import { Client } from "../Client";
 import { FACTOR_SET_API_PATH, GET } from "../Constants";
+import { FactorSetResponse } from "../interfaces/response/FactorSetResponse";
 import { makeApiRequest } from "../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
  * const factorSets = await get();
  */
 export async function get(
-): Promise<string> {
+): Promise<FactorSetResponse> {
 const client = Client.getInstance();
   const url = client.getDomain() + FACTOR_SET_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<FactorSetResponse>({
     method: GET,
     url
   });

package/src/api/Fugitive.ts

@@ -1,43 +1,118 @@
 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 { AreaResponse } from "../interfaces/response/AreaResponse";
+import { EmissionResponse } from "../interfaces/response/EmissionResponse";
+import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResponseWithDetails";
+import { TypeResponse } from "../interfaces/response/TypeResponse";
+import { UnitResponse } from "../interfaces/response/UnitResponse";
 import { makeApiRequest } from "../request";
 
 /**
  * Performs scope 1 fugitve emission calculations by making a POST request to the fugitive API endpoint.
- * 
+ *
  * @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
  * 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);
  */
 
 export async function calculate(
   payload: CommonRequest
-): Promise<string> {
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
   const client = Client.getInstance();
   const url =  client.getDomain() + FUGITIVE_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
     method: POST,
     url,
     data: payload,
   });
 }
+
+/**
+ * Retrieves available fugitive emission calculation types by making a GET request to the API endpoint.
+ *
+ * @export
+ * @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
+ * const types = await getTypes();
+ */
+export async function getTypes(
+): Promise<TypeResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FUGITIVE_API_TYPES;
+
+  return makeApiRequest<TypeResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves information about geographical areas supported by the fugitive emissions API.
+ *
+ * @export
+ * @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();
+ */
+export async function getArea(
+): Promise<AreaResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FUGITIVE_API_AREA;
+
+  return makeApiRequest<AreaResponse>({
+    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<UnitResponse>} A promise that resolves to a UnitResponse 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<UnitResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + FUGITIVE_API_UNITS;
+
+  return makeApiRequest<UnitResponse>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/api/Location.ts

@@ -1,43 +1,117 @@
 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 { AreaResponse } from "../interfaces/response/AreaResponse";
+import { EmissionResponse } from "../interfaces/response/EmissionResponse";
+import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResponseWithDetails";
+import { TypeResponse } from "../interfaces/response/TypeResponse";
+import { UnitResponse } from "../interfaces/response/UnitResponse";
 import { makeApiRequest } from "../request";
 
 /**
  * Performs scope 2 purchased energy Emission calculations by making a POST request to the location API endpoint.
- * 
+ *
  * @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
  * 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(
   payload: LocationRequest
-): Promise<string> {
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
   const client = Client.getInstance();
   const url = client.getDomain() + LOCATION_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
     method: POST,
     url,
     data: payload,
   });
 }
+
+
+/**
+ * Retrieves available location-based calculation types by making a GET request to the location types API endpoint.
+ *
+ * @export
+ * @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
+ *
+ * const types = await getTypes();
+ */
+export async function getTypes(
+): Promise<TypeResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + LOCATION_TYPES;
+
+  return makeApiRequest<TypeResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves information about geographical areas supported by the location-based calculation API.
+ *
+ * @export
+ * @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();
+ */
+export async function getArea(
+): Promise<AreaResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + LOCATION_API_AREA;
+
+  return makeApiRequest<AreaResponse>({
+    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<UnitResponse>} A promise that resolves to a UnitResponse 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<UnitResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + LOCATION_API_UNITS;
+
+  return makeApiRequest<UnitResponse>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}