emissions-api-sdk 1.0.1 → 1.0.3

package/src/api/TransportationAndDistribution.ts

@@ -1,16 +1,21 @@
 import { Client } from "../Client";
 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" : {
@@ -30,11 +35,11 @@ import { makeApiRequest } from "../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,
@@ -46,18 +51,18 @@ export async function calculate(
  * Retrieves available transportation and distribution 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 transportation and distribution calculation types
+ * @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<string> {
+): Promise<TypeResponse> {
   const client = Client.getInstance();
   const url = client.getDomain() + TRANSPORTATION_AND_DISTRIBUTION_API_TYPES;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<TypeResponse>({
     method: GET,
     url
   });
@@ -67,18 +72,18 @@ export async function getTypes(
  * Retrieves information about geographical areas supported by the transportation and distribution API.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @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<string> {
+): Promise<AreaResponse> {
   const client = Client.getInstance();
   const url = client.getDomain() + TRANSPORTATION_AND_DISTRIBUTION_API_AREA;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<AreaResponse>({
     method: GET,
     url
   });
@@ -89,23 +94,23 @@ export async function getArea(
  *
  * @export
  * @param {string} type - The transportation and distribution calculation type to get units for (e.g., "Freight - Cargo Ship")
- * @return {Promise<string>} A promise that resolves to a string containing the available units
+ * @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<string> {
+): Promise<UnitResponse> {
   const client = Client.getInstance();
   const url = client.getDomain() + TRANSPORTATION_AND_DISTRIBUTION_API_UNITS;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<UnitResponse>({
     method: GET,
     url,
     params : { type }

package/src/api/Usage.ts

@@ -0,0 +1,26 @@
+import { Client } from "../Client";
+import { GET, USAGE_API } from "../Constants";
+import { UsageResponse } from "../interfaces/response/UsageResponse";
+import { makeApiRequest } from "../request";
+
+/**
+ * Retrieves current billing period or historical usage data for the user by making a GET request to the API endpoint.
+ *
+ * @export
+ * @param {boolean} history - Flag to retrieve current billing or historical usage data.
+ * @return {Promise<UsageResponse>} A promise that resolves to a UsageResponse containing the organization's usage data
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const usage = await getUsage();
+ */
+export async function getUsage(history : boolean = false): Promise<UsageResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + USAGE_API;
+
+  return makeApiRequest<UsageResponse>({
+    method: GET,
+    url,
+    params : { history }
+  });
+}

package/src/index.ts

@@ -5,6 +5,40 @@ export * as Mobile from './api/Mobile';
 export * as Stationary from './api/Stationary';
 export * as Calculation  from './api/Calculation';
 export * as TransportationAndDistribution from './api/TransportationAndDistribution';
+export * as Usage from './api/Usage'
 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';
+export { UsageResponse } from './interfaces/response/UsageResponse';

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;
+}
+

package/src/interfaces/response/FactorResponse.ts

@@ -0,0 +1,78 @@
+/**
+ * Interface representing the response from the retrieve factor API
+ */
+export interface FactorResponse {
+  /** Unique transaction identifier */
+  transactionId: string;
+  
+  /** Total CO2 equivalent emissions (optional - not present in all responses)*/
+  totalCO2e?: number;
+  
+  /** CO2 emissions value (optional - not present in all responses) */
+  CO2?: number;
+  
+  /** CH4 (Methane) emissions value (optional - not present in all responses) */
+  CH4?: number;
+  
+  /** N2O (Nitrous Oxide) emissions value (optional - not present in all responses) */
+  N2O?: number;
+
+ /** Biogenic CO2 emissions value (optional - not present in all responses) */
+ bioCO2?: number;
+
+ /** Indirect CO2 equivalent emissions value (optional - not present in all responses) */
+ indirectCO2e?: number;
+
+ /** Hydrofluorocarbon emissions value (optional - not present in all responses) */
+ HFC?: number;
+
+ /** Perfluorocarbon emissions value (optional - not present in all responses) */
+ PFC?: number;
+
+ /** Sulfur hexafluoride emissions value (optional - not present in all responses) */
+ SF6?: number;
+
+ /** Nitrogen trifluoride emissions value (optional - not present in all responses) */
+ NF3?: number;
+
+  
+  /** Unit of measurement for emissions */
+  unit?: string;
+  
+  /** Description of the emission factors (optional)*/
+  description?: string;
+  
+  /** Factor set identifier (e.g., "IPCC", "IGES") */
+  factorSet: string;
+  
+  /** Source reference for the emission factors (optional)*/
+  source?: string;
+  
+  /** Type of activity (e.g., "Gas/Diesel Oil", "Electricity") */
+  activityType: string;
+  
+  /** Array of supported activity units */
+  activityUnit: string[];
+  
+  /** Name of the emission factor */
+  name?: string;
+  
+  /** Publication start date in ISO format (optional)*/
+  publishedFrom?: string;
+  
+  /** Publication end date in ISO format (optional) */
+  publishedTo?: string;
+
+  /** Effective start date in ISO format (optional) */
+  effectiveFrom?: string;
+
+  /** Effective end date in ISO format (optional) */
+  effectiveTo?: string;
+
+  
+  /** Geographic region (e.g., "Earth", "India") */
+  region: string;
+  
+  /** Unique factor identifier */
+  factorId: number;
+}

package/src/interfaces/response/FactorSetResponse.ts

@@ -0,0 +1,52 @@
+/**
+ * Interface for individual factor set within the response
+ */
+export interface FactorSet {
+  /** Unique identifier for the factor set (required) */
+  id: number;
+  
+  /** Name of the factor set (required) */
+  name: string;
+  
+  /** License type for the factor set (required, e.g., "Public") */
+  license: string;
+  
+  /** Number of factors in this set (required) */
+  factorCount: number;
+  
+  /** Source URL for the factor set data */
+  sourceUrl?: string;
+  
+  /** Detailed description of the factor set */
+  description?: string;
+  
+  /** Short description of the factor set */
+  descriptionShort?: string;
+  
+  /** Array of emission factor types included in this set */
+  types?: string[];
+  
+  /** Array of regions/countries covered by this factor set */
+  regions?: string[];
+  
+  /** Array of version years available for this factor set */
+  versions?: string[];
+  
+  /** Provider/publisher of the factor set */
+  provider?: string;
+  
+  /** Optional citation information for the factor set */
+  citation?: string;
+}
+
+/**
+ * Interface for Factor Set API response
+ */
+export interface FactorSetResponse {
+  /** Transaction ID for the API request */
+  transactionId: string;
+  
+  /** Array of factor sets returned in the response */
+  factorSets: FactorSet[];
+}
+

package/src/interfaces/response/SearchResponse.ts

@@ -0,0 +1,52 @@
+import { FactorResponse } from './FactorResponse';
+
+/**
+ * Pagination parameters for search requests
+ */
+export interface Pagination {
+  /** Page number */
+  page: number;
+  
+  /** Page size */
+  size: number;
+}
+
+/**
+ * Request body structure for pagination links
+ */
+export interface PaginationBody {
+  /** Pagination parameters */
+  pagination?: Pagination;
+}
+
+/**
+ * Link object for pagination in search results
+ */
+export interface SearchLink {
+  /** Relationship type (e.g., "next", "prev") */
+  rel: string;
+  
+  /** URL for the link */
+  href: string;
+  
+  /** Content type */
+  type: string;
+  
+  /** HTTP method */
+  method: string;
+  
+  /** Request body for pagination */
+  body?: PaginationBody;
+}
+
+/**
+ * Interface representing the response from the search factor API
+ */
+export interface SearchResponse {
+  /** Array of factor results */
+  factors: FactorResponse[];
+  
+  /** Pagination links (optional) */
+  links?: SearchLink[];
+}
+

package/src/interfaces/response/TypeResponse.ts

@@ -0,0 +1,7 @@
+/**
+ * Interface for type metadata API 
+ */
+export interface TypeResponse {
+  /** Array of string*/
+  types: string[];
+}

package/src/interfaces/response/UnitResponse.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface for unit object
+ */
+export interface Unit {
+  /** Unit symbol */
+  unit: string;
+  /** Unit name */
+  unitName: string;
+}
+
+/**
+ * Interface for /units metadata API
+ */
+export interface UnitResponse {
+  /** Array of Unit objects */
+  units: Unit[];
+}

package/src/interfaces/response/UsageResponse.ts

@@ -0,0 +1,23 @@
+/**
+ * Interface representing the GHG Metrics Usage Response
+ */
+
+export interface UsageResponse {
+    /** Organization ID for the API request */
+    orgId ?: string;
+
+    /** Array of entitlement belonging to the Org */
+    entitlement ?: Entitlement[]
+}
+
+
+export interface Entitlement {
+    /** Organization's billing start date*/
+    startDate ?: string;
+
+    /** Organization's billing end date */
+    endDate ?: string;
+
+    /** Total api calls made by the Organization in the billing cycle */
+    totalApiCalls ?: number;
+}