emissions-api-sdk 1.0.4 → 1.0.6

package/sphinx-build/source/reference.rst

@@ -27,61 +27,41 @@ API
 
 .. js:autofunction:: TransportationAndDistribution.calculate
 
-Metadata APIs
-===========
+.. js:autofunction:: RealEstate.calculate
 
-getTypes
---------
+.. js:autofunction:: EconomicActivity.calculate
 
-.. js:autofunction:: Factor.getTypes
 
-.. js:autofunction:: Calculation.getTypes
+Global Metadata API
+====================
 
-.. js:autofunction:: Location.getTypes
+The global Metadata API provides a unified way to query metadata across different endpoints without calling endpoint-specific methods.
 
-.. js:autofunction:: Mobile.getTypes
+- **getTypes/postTypes** and **getArea/postArea**: Accept an optional ``endpoint`` parameter to query metadata for specific endpoints
+- **getUnits/postUnits**: Accept an optional ``type`` parameter to query units for specific emission types
 
-.. js:autofunction:: Stationary.getTypes
+**Supported endpoints** (for getTypes/postTypes and getArea/postArea): ``calculation``, ``location``, ``stationary``, ``mobile``, ``fugitive``, ``factor``, ``search``, ``transportation-and-distribution``, ``economic-activity``, ``real-estate``
 
-.. js:autofunction:: TransportationAndDistribution.getTypes
+getTypes
+--------
 
-.. js:autofunction:: Fugitive.getTypes
+.. js:autofunction:: Metadata.getTypes
+
+.. js:autofunction:: Metadata.postTypes
 
 getArea
 -------
 
-.. js:autofunction:: Factor.getArea
-
-.. js:autofunction:: Factor.getSearchArea
-
-.. js:autofunction:: Calculation.getArea
-
-.. js:autofunction:: Location.getArea
+.. js:autofunction:: Metadata.getArea
 
-.. js:autofunction:: Mobile.getArea
-
-.. js:autofunction:: Stationary.getArea
-
-.. js:autofunction:: TransportationAndDistribution.getArea
-
-.. js:autofunction:: Fugitive.getArea
+.. js:autofunction:: Metadata.postArea
 
 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:: Metadata.getUnits
 
-.. js:autofunction:: Fugitive.getUnits
+.. js:autofunction:: Metadata.postUnits
 
 
 Usage API

package/src/Constants.ts

@@ -9,34 +9,15 @@ 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 ECONOMIC_ACTIVITY_API_PATH = "/v3/carbon/economic-activity";
+export const REAL_ESTATE_API_PATH = "/v3/carbon/real-estate";
 
 export const USAGE_API = "/v3/carbon/usage";
 
+export const METADATA_TYPES_ENDPOINT = "/v3/carbon/metadata/types";
+export const METADATA_AREA_ENDPOINT = "/v3/carbon/metadata/area";
+export const METADATA_UNITS_ENDPOINT = "/v3/carbon/metadata/units";
+
 export const GET = "GET";
 export const POST = "POST";
 export const CLIENT_SOURCE_HEADER = "X-Client-Source";

package/src/api/Calculation.ts

@@ -1,11 +1,8 @@
 import { Client } from "../Client";
-import { GENERIC_CALCULATION_API_PATH,CALCULATION_TYPES, POST, GET, GENERAL_API_AREA, GENERAL_API_UNITS } from "../Constants";
+import { GENERIC_CALCULATION_API_PATH, POST } 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";
 
 
@@ -48,71 +45,3 @@ export async function calculate(
   });
 }
 
-
-/**
- * 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/EconomicActivity.ts

@@ -0,0 +1,45 @@
+import { Client } from "../Client";
+import { ECONOMIC_ACTIVITY_API_PATH, POST } from "../Constants";
+import { CommonRequest } from "../interfaces/Api";
+import { EmissionResponse } from "../interfaces/response/EmissionResponse";
+import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResponseWithDetails";
+import { makeApiRequest } from "../request";
+
+/**
+ * Performs scope 3 Spend based emission calculations by making a POST request to the economic activity API endpoint.
+ *
+ * @export
+ * @param {CommonRequest} payload - The request data to be sent to 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": "accomodation",
+      "value": 1500.12,
+      "unit": "usd"
+    },
+    "includeDetails": false
+  };
+ * const result = await calculate(request);
+ */
+
+export async function calculate(
+  payload: CommonRequest
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
+  const client = Client.getInstance();
+  const url =  client.getDomain() + ECONOMIC_ACTIVITY_API_PATH;
+
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}

package/src/api/Factor.ts

@@ -1,11 +1,8 @@
 import { Client } from "../Client";
-import { FACTOR_API_AREA, FACTOR_API_PATH, FACTOR_API_TYPES, FACTOR_API_UNITS, GET, POST, SEARCH_API_AREA, SEARCH_API_PATH } from "../Constants";
+import { FACTOR_API_PATH, POST, 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";
 
 /**
@@ -87,94 +84,4 @@ export async function search(
     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/Fugitive.ts

@@ -1,11 +1,8 @@
 import { Client } from "../Client";
-import { FUGITIVE_API_AREA, FUGITIVE_API_PATH, FUGITIVE_API_TYPES, FUGITIVE_API_UNITS, GET, POST } from "../Constants";
+import { FUGITIVE_API_PATH, 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";
 
 /**
@@ -46,73 +43,3 @@ export async function calculate(
     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,11 +1,8 @@
 import { Client } from "../Client";
-import { GET, LOCATION_API_AREA, LOCATION_API_PATH, LOCATION_API_UNITS, LOCATION_TYPES, POST } from "../Constants";
+import { LOCATION_API_PATH, 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";
 
 /**
@@ -45,73 +42,4 @@ export async function calculate(
     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 }
-  });
 }