emissions-api-sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,46 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FactorSets = exports.Factor = exports.TransportationAndDistribution = exports.Calculation = exports.Stationary = exports.Mobile = exports.Fugitive = exports.Location = exports.Client = void 0;
+var Client_1 = require("./Client");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return Client_1.Client; } });
+exports.Location = __importStar(require("./api/Location"));
+exports.Fugitive = __importStar(require("./api/Fugitive"));
+exports.Mobile = __importStar(require("./api/Mobile"));
+exports.Stationary = __importStar(require("./api/Stationary"));
+exports.Calculation = __importStar(require("./api/Calculation"));
+exports.TransportationAndDistribution = __importStar(require("./api/TransportationAndDistribution"));
+exports.Factor = __importStar(require("./api/Factor"));
+exports.FactorSets = __importStar(require("./api/FactorSets"));

package/dist/interfaces/Api.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/Config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/common.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/request.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeApiRequest = makeApiRequest;
+const axios_1 = __importDefault(require("axios"));
+const Client_1 = require("./Client");
+const Constants_1 = require("./Constants");
+/**
+ * Makes an API request with standardized headers and token refresh.
+ *
+ * @export
+ * @template T The expected response data type
+ * @param {RequestConfig} config - The request configuration including method, URL, data, params, and optional headers
+ * @return {Promise<T>} A promise that resolves to the response data of type T
+ * @throws {Error} May throw an error if the API request fails or token refresh fails
+ *
+ * @example
+ * interface UserData {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const userData = await makeApiRequest<UserData>({
+ *   method: 'GET',
+ *   url: 'https://api.example.com/users/123',
+ *   headers: { 'X-Custom-Header': 'value' }
+ * });
+ * console.log(userData.name); // Typed access to the response data
+ */
+async function makeApiRequest(config) {
+    const client = Client_1.Client.getInstance();
+    await client.refreshToken();
+    const axiosConfig = {
+        method: config.method,
+        url: config.url,
+        data: config.data,
+        params: config.params,
+        headers: {
+            ...client.getAuthHeader(),
+            ...config.headers,
+            'Content-Type': 'application/json',
+            'X-IBM-Client-Id': `ghgemissions-${client.getClientId()}`,
+            [Constants_1.CLIENT_SOURCE_HEADER]: client.getClientSource()
+        },
+    };
+    const response = await axios_1.default.request(axiosConfig);
+    return response.data;
+}

package/dist/types/Client.d.ts

@@ -0,0 +1,146 @@
+import { ClientConfig } from "./interfaces/Config";
+export declare class Client {
+    private static instance;
+    private token;
+    private readonly apiKey;
+    private readonly clientId;
+    private readonly orgId;
+    private expiresAt;
+    private readonly domain;
+    private readonly tokenDomain;
+    private readonly isUserProvidedToken;
+    private readonly clientSource;
+    private constructor();
+    /**
+     * 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'
+     * });
+     */
+    static getClient(config: ClientConfig): Promise<void>;
+    /**
+     * 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'
+     */
+    getDomain(): string;
+    /**
+     * 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...
+     */
+    static getInstance(): Client;
+    /**
+     * 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...
+     */
+    refreshToken(): Promise<void>;
+    /**
+     * 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...' }
+     */
+    getAuthHeader(): Record<string, string>;
+    /**
+     * 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'
+     */
+    getClientId(): string;
+    /**
+     * 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'
+     */
+    getClientSource(): string;
+    /**
+     * 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 requestToken;
+}

package/dist/types/Constants.d.ts

@@ -0,0 +1,16 @@
+export declare const API_DOMAIN = "https://api.ibm.com/ghgemissions/run";
+export declare const TOKEN_GENERATION_API = "https://api.ibm.com/saascore/run/authentication-retrieve/api-key";
+export declare const MOBILE_API_PATH = "/v3/carbon/mobile";
+export declare const LOCATION_API_PATH = "/v3/carbon/location";
+export declare const FUGITIVE_API_PATH = "/v3/carbon/fugitive";
+export declare const STATIONARY_API_PATH = "/v3/carbon/stationary";
+export declare const GENERIC_CALCULATION_API_PATH = "/v3/carbon/calculation";
+export declare const TRANSPORTATION_AND_DISTRIBUTION_API_PATH = "/v3/carbon/transportation-and-distribution";
+export declare const FACTOR_API_PATH = "/v3/carbon/factor";
+export declare const FACTOR_SET_API_PATH = "/v3/carbon/factorset";
+export declare const SEARCH_API_PATH = "/v3/carbon/factor/search";
+export declare const GET = "GET";
+export declare const POST = "POST";
+export declare const CLIENT_SOURCE_HEADER = "X-Client-Source";
+export declare const CLIENT_SOURCE_EXCEL = "excel";
+export declare const CLIENT_SOURCE_SDK = "node-sdk";

package/dist/types/api/Calculation.d.ts

@@ -0,0 +1,28 @@
+import { CalculationRequest } from "../interfaces/Api";
+/**
+ * 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 declare function calculate(payload: CalculationRequest): Promise<string>;

package/dist/types/api/Factor.d.ts

@@ -0,0 +1,57 @@
+import { FactorRequest, SearchRequest } from "../interfaces/Api";
+/**
+ * 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 declare function retrieveFactor(payload: FactorRequest): Promise<string>;
+/**
+ * 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 declare function search(payload: SearchRequest): Promise<string>;

package/dist/types/api/FactorSets.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function get(): Promise<string>;

package/dist/types/api/Factors.d.ts

@@ -0,0 +1,68 @@
+import { FactorRequest, SearchRequest } from "../interfaces/Api";
+/**
+ * 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 declare function retrieveFactor(payload: FactorRequest): Promise<string>;
+/**
+ * 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 getFactorSets();
+ */
+export declare function getFactorSets(): Promise<string>;
+/**
+ * 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 declare function Search(payload: SearchRequest): Promise<string>;

package/dist/types/api/Fugitive.d.ts

@@ -0,0 +1,27 @@
+import { CommonRequest } from "../interfaces/Api";
+/**
+ * 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 declare function calculate(payload: CommonRequest): Promise<string>;

package/dist/types/api/FugitiveEmission.d.ts

@@ -0,0 +1,27 @@
+import { CommonRequest } from "../interfaces/Api";
+/**
+ * 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 declare function calculate(payload: CommonRequest): Promise<string>;

package/dist/types/api/GenericCalculation.d.ts

@@ -0,0 +1,28 @@
+import { GenericCalculationRequest } from "../interfaces/Api";
+/**
+ * Performs emission calculations by making a POST request to the generic calculation API endpoint.
+ *
+ * @export
+ * @param {GenericCalculationRequest} 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 declare function calculate(payload: GenericCalculationRequest): Promise<string>;

package/dist/types/api/Location.d.ts

@@ -0,0 +1,28 @@
+import { LocationRequest } from "../interfaces/Api";
+/**
+ * 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 declare function calculate(payload: LocationRequest): Promise<string>;

package/dist/types/api/LocationEmission.d.ts

@@ -0,0 +1,28 @@
+import { LocationRequest } from "../interfaces/Api";
+/**
+ * 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 declare function calculate(payload: LocationRequest): Promise<string>;

package/dist/types/api/Mobile.d.ts

@@ -0,0 +1,28 @@
+import { CommonRequest } from "../interfaces/Api";
+/**
+ * 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 declare function calculate(payload: CommonRequest): Promise<string>;

package/dist/types/api/MobileEmission.d.ts

@@ -0,0 +1,28 @@
+import { CommonRequest } from "../interfaces/Api";
+/**
+ * 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 declare function calculate(payload: CommonRequest): Promise<string>;

package/dist/types/api/Stationary.d.ts

@@ -0,0 +1,28 @@
+import { CommonRequest } from "../interfaces/Api";
+/**
+ * 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 declare function calculate(payload: CommonRequest): Promise<string>;