emissions-api-sdk 1.0.0 → 1.0.2

package/src/api/Mobile.ts

@@ -1,17 +1,22 @@
 import { makeApiRequest } from "../request";
-import { MOBILE_API_PATH, POST } from "../Constants";
+import { GET, MOBILE_API_AREA, MOBILE_API_PATH, MOBILE_API_TYPES, MOBILE_API_UNITS, 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 { Client } from "../Client";
 
 
 /**
  * Performs Scope 1 mobile emissions related calculations by making a POST request to the mobile API endpoint.
- * 
+ *
  * @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
  * const request = {
     "time": {
@@ -33,13 +38,85 @@ import { Client } from "../Client";
 
 export async function calculate(
   payload: CommonRequest
-): Promise<string> {
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
   const client = Client.getInstance();
   const url = client.getDomain() + MOBILE_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
     method: POST,
     url,
     data: payload,
   });
 }
+
+
+/**
+ * Retrieves available mobile 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 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();
+ */
+export async function getTypes(
+): Promise<TypeResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + MOBILE_API_TYPES;
+
+  return makeApiRequest<TypeResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves information about geographical areas supported by the mobile 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() + MOBILE_API_AREA;
+
+  return makeApiRequest<AreaResponse>({
+    method: 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<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 "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");
+ */
+export async function getUnits(
+  type : string
+): Promise<UnitResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + MOBILE_API_UNITS;
+
+  return makeApiRequest<UnitResponse>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/api/Stationary.ts

@@ -1,45 +1,120 @@
 import { Client } from "../Client";
-import { POST, STATIONARY_API_PATH } from "../Constants";
+import { GET, POST, STATIONARY_API_AREA, STATIONARY_API_PATH, STATIONARY_API_TYPES, STATIONARY_API_UNITS } 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 stationary calculations by making a POST request to the stationary API endpoint.
- * 
+ *
  * @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
  * const request = {
-             "time" : {
-                "date": "2025-01-04"
-            },
-            "location": {
-                "country": "usa",
-								"stateProvince": "new york"
-            },
-            "activity": {
-							"type":"Coal - Lignite",
-							"unit": "KJ",
-							"value": 3
-            },
-            "includeDetails": true
-      };
+    "time" : {
+      "date": "2025-01-04"
+    },
+    "location": {
+      "country": "usa",
+      "stateProvince": "new york"
+    },
+    "activity": {
+      "type":"Coal - Lignite",
+      "unit": "KJ",
+      "value": 3
+    },
+    "includeDetails": true
+  };
  * const result = await calculate(request);
  */
 
 export async function calculate(
   payload: CommonRequest
-): Promise<string> {
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
   const client = Client.getInstance();
   const url =  client.getDomain() + STATIONARY_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
     method: POST,
     url,
     data: payload,
   });
 }
+
+/**
+ * Retrieves available stationary 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 stationary 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() + STATIONARY_API_TYPES;
+
+  return makeApiRequest<TypeResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves information about geographical areas supported by the stationary 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() + STATIONARY_API_AREA;
+
+  return makeApiRequest<AreaResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves available units for a specific stationary emission type.
+ *
+ * @export
+ * @param {string} type - The stationary emission type to get units for (e.g., "Coal - Lignite")
+ * @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 "Petroleum Based Greases - NC:A" emission stationary type with subtype
+ * const units = await getUnits("Petroleum Based Greases - NC:A");
+
+ * Get units for the "Jet Kerosene" emission stationary type without subtype
+ * const units = await getUnits("Jet Kerosene");
+ */
+export async function getUnits(
+  type : string
+): Promise<UnitResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + STATIONARY_API_UNITS;
+
+  return makeApiRequest<UnitResponse>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/api/TransportationAndDistribution.ts

@@ -1,42 +1,118 @@
 import { Client } from "../Client";
-import { TRANSPORTATION_AND_DISTRIBUTION_API_PATH, POST } from "../Constants";
+import { TRANSPORTATION_AND_DISTRIBUTION_API_PATH, POST, TRANSPORTATION_AND_DISTRIBUTION_API_TYPES, GET, TRANSPORTATION_AND_DISTRIBUTION_API_AREA, TRANSPORTATION_AND_DISTRIBUTION_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 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
  * const request = {
-             "time" : {
-                "date": "2025-01-04"
-            },
-            "location": {
-                "country": "usa"
-            },
-            "activity": {
-            	"type": "Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt",
-							"unit": ["t","km"],
-							"value": [1.0,1.0]
-            },
-            "includeDetails": true
+    "time" : {
+      "date": "2025-01-04"
+    },
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "type": "Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt",
+      "unit": ["t","km"],
+      "value": [1.0,1.0]
+    },
+    "includeDetails": true
   };
  * const result = await calculate(request);
  */
 export async function calculate(
   payload: CalculationRequest
-): Promise<string> {
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
   const client = Client.getInstance();
   const url = client.getDomain() + TRANSPORTATION_AND_DISTRIBUTION_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
     method: POST,
     url,
     data: payload,
   });
 }
+
+
+/**
+ * Retrieves available transportation and distribution 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 transportation and distribution 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() + TRANSPORTATION_AND_DISTRIBUTION_API_TYPES;
+
+  return makeApiRequest<TypeResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves information about geographical areas supported by the transportation and distribution 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() + TRANSPORTATION_AND_DISTRIBUTION_API_AREA;
+
+  return makeApiRequest<AreaResponse>({
+    method: GET,
+    url
+  });
+}
+
+/**
+ * Retrieves available units for a specific transportation and distribution calculation type.
+ *
+ * @export
+ * @param {string} type - The transportation and distribution calculation type to get units for (e.g., "Freight - Cargo Ship")
+ * @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 "Business Travel - Cars:Diesel - Small" transportation and distribution type without subtype
+ * const units = await getUnits("Business Travel - Cars:Diesel - Small");
+ *
+ * // Get units for the "Business Travel - Cars" transportation and distribution type with subtype
+ * const units = await getUnits("Business Travel - Cars");
+ */
+export async function getUnits(
+  type : string
+): Promise<UnitResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + TRANSPORTATION_AND_DISTRIBUTION_API_UNITS;
+
+  return makeApiRequest<UnitResponse>({
+    method: GET,
+    url,
+    params : { type }
+  });
+}

package/src/index.ts

@@ -7,4 +7,36 @@ export * as Calculation  from './api/Calculation';
 export * as TransportationAndDistribution from './api/TransportationAndDistribution';
 export * as Factor from './api/Factor';
 export * as FactorSets from './api/FactorSets'
-export { ClientConfig } from './interfaces/Config';
+export { ClientConfig } from './interfaces/Config';
+
+// Response interfaces
+export { AreaResponse, Location as LocationInfo } from './interfaces/response/AreaResponse';
+export { EmissionResponse } from './interfaces/response/EmissionResponse';
+export {
+  EmissionResponseWithDetails,
+  UnitInfo,
+  AreaInfo,
+  AreaType,
+  FactorDataTypeCategory,
+  FactorSetInfo,
+  FactorSelectionDefault,
+  FactorDataTypeCode,
+  FactorSetVersion,
+  FactorValue,
+  FactorMetaData,
+  UnitConversion,
+  EmissionData
+} from './interfaces/response/EmissionResponseWithDetails';
+export { FactorResponse } from './interfaces/response/FactorResponse';
+export {
+  FactorSetResponse,
+  FactorSet
+} from './interfaces/response/FactorSetResponse';
+export {
+  SearchResponse,
+  Pagination,
+  PaginationBody,
+  SearchLink
+} from './interfaces/response/SearchResponse';
+export { TypeResponse } from './interfaces/response/TypeResponse';
+export { UnitResponse } from './interfaces/response/UnitResponse';

package/src/interfaces/response/AreaResponse.ts

@@ -0,0 +1,25 @@
+/**
+ * Interface representing a location with geographical and power grid information
+ */
+export interface Location {
+  /** ISO 3166-1 alpha-3 country code */
+  alpha3: string;
+  
+  /** Full country name */
+  countryName: string;
+  
+  /** List of state or province names (optional) */
+  stateProvinces?: string[];
+  
+  /** List of power grid identifiers (optional) */
+  powerGrids?: string[];
+}
+
+/**
+ * Interface representing the response from the area/location API
+ */
+export interface AreaResponse {
+  /** Array of location objects */
+  locations: Location[];
+}
+

package/src/interfaces/response/EmissionResponse.ts

@@ -0,0 +1,44 @@
+/**
+ * Interface representing the emission calculation response
+ */
+export interface EmissionResponse {
+  /** Unique transaction identifier (required) */
+  transactionId: string;
+  
+  /** Total CO2 equivalent emissions (required) */
+  totalCO2e: number;
+  
+  /** CO2 emissions value (optional) */
+  CO2?: number;
+  
+  /** CH4 (Methane) emissions value (optional) */
+  CH4?: number;
+  
+  /** N2O (Nitrous Oxide) emissions value (optional) */
+  N2O?: number;
+  
+  /** Biogenic CO2 emissions value (optional) */
+  bioCO2?: number;
+  
+  /** Indirect CO2 equivalent emissions value (optional) */
+  indirectCO2e?: number;
+  
+  /** Hydrofluorocarbon emissions value (optional) */
+  HFC?: number;
+  
+  /** Perfluorocarbon emissions value (optional) */
+  PFC?: number;
+  
+  /** Sulfur hexafluoride emissions value (optional) */
+  SF6?: number;
+  
+  /** Nitrogen trifluoride emissions value (optional) */
+  NF3?: number;
+
+   /** Unit of measurement for emissions (required) */
+  unit: string;
+  
+  /** Description of the emission calculation (required) */
+  description: string;
+}
+

package/src/interfaces/response/EmissionResponseWithDetails.ts

@@ -0,0 +1,183 @@
+import { EmissionResponse } from './EmissionResponse';
+
+/**
+ * Interface for unit information in emission details
+ */
+export interface UnitInfo {
+  /** Unit name */
+  name: string;
+  
+  /** Unit description (optional) */
+  description?: string;
+}
+
+/**
+ * Interface for area information
+ */
+export interface AreaInfo {
+  /** Internal name of the area */
+  internalName: string;
+  
+  /** Standard name of the area */
+  standardName: string;
+
+  alpha3?: string;
+}
+
+/**
+ * Interface for area type information
+ */
+export interface AreaType {
+  /** Type name (e.g., "Planet", "State") */
+  name: string;
+}
+
+/**
+ * Interface for factor data type categories
+ */
+export interface FactorDataTypeCategory {
+  /** Category name */
+  name: string;
+}
+
+/**
+ * Interface for factor set information
+ */
+export interface FactorSetInfo {
+  /** Factor set type */
+  type: string;
+  
+  /** Description of the factor set */
+  description?: string;
+  
+  /** Provider of the factor set */
+  provider?: string;
+  
+  /** Source URL for the factor set */
+  sourceUrl?: string;
+
+  factorSource?: string;
+}
+export interface FactorSelectionDefault {
+    actorDataType?: string;
+    areaName?: string;
+    factorSetName?: string;
+}
+/**
+ * Interface for factor data type code
+ */
+export interface FactorDataTypeCode {
+  /** Unit of measure */
+  unitOfMeasure: string;
+  
+  /** Activity type */
+  type: string;
+  
+  /** Activity subtype */
+  subtype: string;
+  
+  /** Unique factor identifier */
+  factorId: number;
+}
+
+/**
+ * Interface for factor set version information
+ */
+export interface FactorSetVersion {
+  /** Publication start date */
+  publishedFrom?: string;
+  
+  /** Publication end date (optional) */
+  publishedTo?: string;
+  
+  /** Source of the factor */
+  factorSource: string;
+}
+
+/**
+ * Interface for factor value
+ */
+export interface FactorValue {
+  /** Unit information */
+  unit: {
+    /** Unit name */
+    name: string;
+  };
+  
+  /** Factor value */
+  value: number;
+}
+
+/**
+ * Interface for factor metadata
+ */
+export interface FactorMetaData {
+  /** Metadata key */
+  key: string;
+  
+  /** Metadata value */
+  value: string;
+}
+
+/**
+ * Interface for unit conversion information
+ */
+export interface UnitConversion {
+  /** Input unit */
+  inputUnit: string;
+  
+  /** Unit from database */
+  unitFromDb: string;
+  
+  /** Conversion ratio */
+  conversionRatio: string;
+}
+
+/**
+ * Interface for detailed emission data
+ */
+export interface EmissionData {
+  /** Array of unit information */
+  unit: UnitInfo[];
+  
+  /** Array of area information */
+  area: AreaInfo[];
+  
+  /** Array of area types */
+  areaType: AreaType[];
+  
+  /** Array of factor data type categories */
+  factorDataTypeCategories: FactorDataTypeCategory[];
+
+  factorSelectionDefault? :FactorSelectionDefault[];
+  
+  /** Array of factor set information */
+  factorSet: FactorSetInfo[];
+  
+  /** Array of factor data type codes */
+  factorDataTypeCode: FactorDataTypeCode[];
+  
+  /** Array of factor set versions */
+  factorSetVersion: FactorSetVersion[];
+  
+  /** Array of factor values */
+  factorValue: FactorValue[];
+  
+  /** Array of factor metadata */
+  factorMetaData: FactorMetaData[];
+  
+  /** Array of unit conversions */
+  unitConversion: UnitConversion[];
+}
+
+/**
+ * Interface representing the emission calculation response with detailed information
+ */
+export interface EmissionResponseWithDetails {
+  /** Emission calculation result */
+  result: EmissionResponse;
+  
+  /** Detailed emission data */
+  data: EmissionData;
+}
+