emissions-api-sdk 1.0.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "emissions-api-sdk",
+  "version": "1.0.0",
+  "description": "sdk for IBM Emissions APIs",
+  "main": "dist/index.js",
+  "types": "dist/types/index.d.ts",
+  "scripts": {
+    "test": "jest",
+    "build": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IBM/ibm-envizi-emissions-api-nodejs-sdk"
+  },
+  "keywords": [
+    "EMISSIONS-API-SDK",
+    "EMISSIONS-SDK",
+    "IBM",
+    "GHG",
+    "IBMGHG",
+    "SDK",
+    "IBM-SDK",
+    "EMISSION",
+    "GHG-SDK",
+    "GREEEN HOUSE GAS",
+    "EMISSIONS",
+    "EMISSIONS-API",
+    "EMISSIONS API",
+    "GHG EMISSIONS",
+    "IBM-GHG",
+    "SCOPE 3 EMISSIONS",
+    "SCOPE 2 EMISSIONS",
+    "SCOPE 1 EMISSIONS"
+  ],
+  "author": "santhosh0703,Prakhar-sahu,taylorsteffanj",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "axios": "^1.12.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.4",
+    "axios-mock-adapter": "^2.1.0",
+    "jest": "^30.0.5",
+    "nock": "^14.0.6",
+    "ts-jest": "^29.4.0",
+    "typedoc": "^0.28.13",
+    "typescript": "^5.9.2"
+  }
+}

package/src/Client.ts

@@ -0,0 +1,252 @@
+import axios from "axios";
+import { ClientConfig } from "./interfaces/Config";
+import { findExpiryTime } from "./utils";
+import { API_DOMAIN, TOKEN_GENERATION_API, CLIENT_SOURCE_EXCEL, CLIENT_SOURCE_SDK } from "./Constants";
+
+export class Client {
+  private static instance: Client | null = null;
+
+  private token: string;
+  private readonly apiKey: string;
+  private readonly clientId: string;
+  private readonly orgId: string;
+  private expiresAt: number;
+  private readonly domain: string;
+  private readonly tokenDomain: string;
+  private readonly isUserProvidedToken: boolean;
+  private readonly clientSource: string;
+
+  private constructor(
+    token: string,
+    config: ClientConfig,
+    isUserProvidedToken = false
+  ) {
+    const { apiKey="", clientId, orgId="", host, authUrl, isExcelAddIn=false } = config;
+    this.token = token;
+    this.clientId = clientId;
+    if (isUserProvidedToken) {
+      this.apiKey = "";
+      this.orgId = "";
+    } else {
+      this.apiKey = apiKey;
+      this.orgId = orgId;
+    }
+
+    const exp = findExpiryTime(token);
+    this.expiresAt = exp;
+    this.domain = host ?? API_DOMAIN;
+    this.tokenDomain = authUrl ?? TOKEN_GENERATION_API;
+    this.isUserProvidedToken = isUserProvidedToken;
+    this.clientSource = isExcelAddIn === true ? CLIENT_SOURCE_EXCEL : CLIENT_SOURCE_SDK;
+  }
+
+/**
+ * Initializes and returns a Client instance with the provided configuration.
+ * 
+ * @static
+ * @param {ClientConfig} config - The client configuration object
+ * @return {Promise<void>} A promise that resolves when the client is initialized
+ * @throws {Error} Throws an error if:
+ *  - custom "host" is provided without "authUrl"
+ *  - token is provided without "clientId"
+ *  - apiKey is provided without "clientId" or "orgId"
+ * 
+ * @example
+ * // Initialize with authentication URL
+ * await Client.getClient({
+ *   host: 'https://api.example.com',
+ *   authUrl: 'https://auth.example.com',
+ *   clientId: 'client123',
+ *   orgId: 'org456'
+ * });
+ * 
+ * // Initialize with existing token
+ * await Client.getClient({
+ *   token: 'existing-jwt-token',
+ *   clientId: 'client123'
+ * });
+ * 
+ * // Initialize with API key
+ * await Client.getClient({
+ *   apiKey: 'your-api-key',
+ *   clientId: 'client123',
+ *   orgId: 'org456'
+ * });
+ */
+
+  public static async getClient(config: ClientConfig): Promise<void> {
+    if (config.host && !config.authUrl) {
+      throw new Error(
+        'If custom "host" is provided, "authUrl" must also be provided.'
+      );
+    }
+    if (config.token && !config.clientId) {
+      throw new Error(
+        'If token is provided directly, "clientId" must also be provided.'
+      );
+    }
+    if(config.apiKey && (!config.orgId || !config.clientId)){
+      throw new Error(
+        'If apiKey is provided , "clientId" and "OrgId" must also be provided.'
+      );
+    }
+    let token: string;
+    let isUserProvidedToken = false;
+
+    if (config.token && config.clientId) {
+      token = config.token;
+      isUserProvidedToken = true;
+    } else token = await Client.requestToken(config);
+    Client.instance = new Client(token, config,isUserProvidedToken);
+  }
+
+  /**
+   * Returns the domain URL configured for the client.
+   * 
+   * @return {string} The domain URL string
+   * 
+   * @example
+   * const client = Client.getInstance();
+   * const apiDomain = client.getDomain();
+   * console.log(apiDomain); // e.g., 'https://api.example.com'
+   */
+  public getDomain(): string {
+    return this.domain;
+  }
+
+  /**
+   * Returns the singleton instance of the Client.
+   * 
+   * @static
+   * @return {Client} The singleton Client instance
+   * @throws {Error} Throws an error if the Client has not been initialized with getClient()
+   * 
+   * @example
+   * // First initialize the client
+   * await Client.getClient({
+   *   clientId: 'client123',
+   *   orgId: 'org456'
+   * });
+   * 
+   * // Then get the instance
+   * const client = Client.getInstance();
+   * // Use the client...
+   */
+  public static getInstance(): Client {
+    if (!Client.instance) {
+      throw new Error(
+        "Client is not initialized. Call Client.getClient() first."
+      );
+    }
+    return Client.instance;
+  }
+
+  /**
+   * Refreshes the authentication token if it's about to expire.
+   * Only refreshes if the token was not provided by the user and is expiring within 60 seconds.
+   * 
+   * @return {Promise<void>} A promise that resolves when the token refresh is complete
+   * 
+   * @example
+   * const client = Client.getInstance();
+   * // Ensure token is fresh before making API requests
+   * await client.refreshToken();
+   * // Proceed with API requests...
+   */
+  public async refreshToken(): Promise<void> {
+    if (!this.isUserProvidedToken) {
+      const now = Math.floor(Date.now() / 1000);
+      if (this.expiresAt - now < 60) {
+        console.log("[SDK] Refreshing token...");
+        const token = await Client.requestToken({
+          apiKey: this.apiKey,
+          clientId: this.clientId,
+          orgId: this.orgId,
+          authUrl: this.tokenDomain,
+        });
+        this.token = token;
+        this.expiresAt = findExpiryTime(token);
+      }
+    }
+  }
+
+  /**
+   * Returns the authorization header object with the Bearer token.
+   * 
+   * @return {Record<string, string>} An object containing the Authorization header with the Bearer token
+   * 
+   * @example
+   * const client = Client.getInstance();
+   * const headers = {
+   *   'Content-Type': 'application/json',
+   *   ...client.getAuthHeader()
+   * };
+   * // headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer token...' }
+   */
+  public getAuthHeader(): Record<string, string> {
+    return { Authorization: `Bearer ${this.token}` };
+  }
+  
+  /**
+   * Returns the client ID configured for this client instance.
+   * 
+   * @return {string} The client ID string
+   * 
+   * @example
+   * const client = Client.getInstance();
+   * const clientId = client.getClientId();
+   * console.log(clientId); // e.g., 'client123'
+   */
+  public getClientId(): string {
+    return this.clientId;
+  }
+
+  /**
+   * Returns the client source identifier for this client instance.
+   * 
+   * @return {string} The client source string
+   * 
+   * @example
+   * const client = Client.getInstance();
+   * const source = client.getClientSource();
+   * console.log(source); // e.g., 'web', 'mobile', 'sdk'
+   */
+  public getClientSource() : string {
+    return this.clientSource;
+  }
+
+  /**
+   * Requests an authentication token from the token generation API.
+   * 
+   * @private
+   * @static
+   * @param {ClientConfig} config - The client configuration containing authentication details
+   * @return {Promise<string>} A promise that resolves to the authentication token string
+   * @throws {Error} Throws an error if the token response is empty
+   * 
+   * @example
+   * // Internal usage within the Client class
+   * const token = await Client.requestToken({
+   *   apiKey: 'your-api-key',
+   *   clientId: 'client123',
+   *   orgId: 'org456',
+   *   authUrl: 'https://custom-auth.example.com/token'
+   * });
+   */
+  private static async requestToken(config: ClientConfig): Promise<string> {
+    const tokenUrl = config.authUrl ?? TOKEN_GENERATION_API;
+    const res = await axios.get(tokenUrl, {
+      headers: {
+        "X-Api-Key": config.apiKey,
+        "X-IBM-Client-Id": `saascore-${config.clientId}`,
+        accept: "application/json",
+      },
+      params: {
+        orgId: config.orgId
+      }
+    });
+
+    if (!res.data) throw new Error("Token response is empty");
+    return String(res.data).trim();
+  }
+}

package/src/Constants.ts

@@ -0,0 +1,16 @@
+export const API_DOMAIN = "https://api.ibm.com/ghgemissions/run";
+export const TOKEN_GENERATION_API = "https://api.ibm.com/saascore/run/authentication-retrieve/api-key";
+export const MOBILE_API_PATH = "/v3/carbon/mobile";
+export const LOCATION_API_PATH = "/v3/carbon/location";
+export const FUGITIVE_API_PATH = "/v3/carbon/fugitive";
+export const STATIONARY_API_PATH = "/v3/carbon/stationary";
+export const GENERIC_CALCULATION_API_PATH = "/v3/carbon/calculation";
+export const TRANSPORTATION_AND_DISTRIBUTION_API_PATH = "/v3/carbon/transportation-and-distribution";
+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 GET = "GET";
+export const POST = "POST";
+export const CLIENT_SOURCE_HEADER = "X-Client-Source";
+export const CLIENT_SOURCE_EXCEL = "excel";
+export const CLIENT_SOURCE_SDK = "node-sdk";

package/src/api/Calculation.ts

@@ -0,0 +1,44 @@
+import { Client } from "../Client";
+import { GENERIC_CALCULATION_API_PATH, POST } from "../Constants";
+import { CalculationRequest } from "../interfaces/Api";
+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
+ * @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
+        };
+ * const result = await calculate(calculationRequest);
+ */
+export async function calculate(
+  payload: CalculationRequest
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + GENERIC_CALCULATION_API_PATH;
+
+  return makeApiRequest<string>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}

package/src/api/Factor.ts

@@ -0,0 +1,86 @@
+import { Client } from "../Client";
+import { FACTOR_API_PATH, POST, SEARCH_API_PATH } from "../Constants";
+import { FactorRequest, SearchRequest } from "../interfaces/Api";
+import { makeApiRequest } from "../request";
+
+/**
+ * Retrieves a factor details by making a POST request to the factor API endpoint.
+ * 
+ * @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
+ * @throws {Error} May throw an error if the API request fails
+ * 
+ * @example
+ * const factorRequest = {
+	
+	"activity": {
+		 "factorId": 12345
+	}
+  };
+  
+  or
+
+  const factorRequest = {
+             "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> {
+  const client = Client.getInstance();
+  const url =  client.getDomain() + FACTOR_API_PATH;
+
+  return makeApiRequest<string>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}
+
+
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ * 
+ * @example
+ * const searchRequest = { 
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search" : "travel"},
+  "location": {
+      "country": "USA"
+    }
+  };
+ * const results = await search(searchRequest);
+ */
+export async function search(
+  payload: SearchRequest
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + SEARCH_API_PATH;
+
+  return makeApiRequest<string>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}

package/src/api/FactorSets.ts

@@ -0,0 +1,24 @@
+import { Client } from "../Client";
+import { FACTOR_SET_API_PATH, GET } from "../Constants";
+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
+ * @throws {Error} May throw an error if the API request fails
+ * 
+ * @example
+ * const factorSets = await get();
+ */
+export async function get(
+): Promise<string> {
+const client = Client.getInstance();
+  const url = client.getDomain() + FACTOR_SET_API_PATH;
+
+  return makeApiRequest<string>({
+    method: GET,
+    url
+  });
+}

package/src/api/Fugitive.ts

@@ -0,0 +1,43 @@
+import { Client } from "../Client";
+import { FUGITIVE_API_PATH, POST } from "../Constants";
+import { CommonRequest } from "../interfaces/Api";
+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
+ * @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
+  };
+ * const result = await calculate(request);
+ */
+
+export async function calculate(
+  payload: CommonRequest
+): Promise<string> {
+  const client = Client.getInstance();
+  const url =  client.getDomain() + FUGITIVE_API_PATH;
+
+  return makeApiRequest<string>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}

package/src/api/Location.ts

@@ -0,0 +1,43 @@
+import { Client } from "../Client";
+import { LOCATION_API_PATH, POST } from "../Constants";
+import { LocationRequest } from "../interfaces/Api";
+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
+ * @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
+        };
+ * const result = await calculate(calculationRequest);
+ */
+export async function calculate(
+  payload: LocationRequest
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + LOCATION_API_PATH;
+
+  return makeApiRequest<string>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}

package/src/api/Mobile.ts

@@ -0,0 +1,45 @@
+import { makeApiRequest } from "../request";
+import { MOBILE_API_PATH, POST } from "../Constants";
+import { CommonRequest } from "../interfaces/Api";
+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
+ * @throws {Error} May throw an error if the API request fails
+ * 
+ * @example
+ * const request = {
+    "time": {
+      "date": "2022-01-01"
+    },
+    "location": {
+      "country": "USA",
+      "stateProvince": "new york"
+    },
+    "activity": {
+      "type": "Diesel Fuel",
+      "value": 1500000,
+      "unit": "l"
+    },
+    "includeDetails": false
+  };
+ * const result = await calculate(request);
+ */
+
+export async function calculate(
+  payload: CommonRequest
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + MOBILE_API_PATH;
+
+  return makeApiRequest<string>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}

package/src/api/Stationary.ts

@@ -0,0 +1,45 @@
+import { Client } from "../Client";
+import { POST, STATIONARY_API_PATH } from "../Constants";
+import { CommonRequest } from "../interfaces/Api";
+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
+ * @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
+      };
+ * const result = await calculate(request);
+ */
+
+export async function calculate(
+  payload: CommonRequest
+): Promise<string> {
+  const client = Client.getInstance();
+  const url =  client.getDomain() + STATIONARY_API_PATH;
+
+  return makeApiRequest<string>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}

package/src/api/TransportationAndDistribution.ts

@@ -0,0 +1,42 @@
+import { Client } from "../Client";
+import { TRANSPORTATION_AND_DISTRIBUTION_API_PATH, POST } from "../Constants";
+import { CalculationRequest } from "../interfaces/Api";
+import { makeApiRequest } from "../request";
+
+/**
+ * Performs Scope 2 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
+ * @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
+  };
+ * const result = await calculate(request);
+ */
+export async function calculate(
+  payload: CalculationRequest
+): Promise<string> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + TRANSPORTATION_AND_DISTRIBUTION_API_PATH;
+
+  return makeApiRequest<string>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}