emissions-api-sdk 1.0.0 → 1.0.1

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

@@ -9,20 +9,58 @@ import { CommonRequest } from "../interfaces/Api";
  *
  * @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 declare function calculate(payload: CommonRequest): Promise<string>;
+/**
+ * Retrieves available stationary emission 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 stationary emission types
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const types = await getTypes();
+ */
+export declare function getTypes(): Promise<string>;
+/**
+ * Retrieves information about geographical areas supported by the stationary emissions API.
+ *
+ * @export
+ * @return {Promise<string>} A promise that resolves to a string containing the supported geographical areas
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const areas = await getArea();
+ */
+export declare function getArea(): Promise<string>;
+/**
+ * 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<string>} A promise that resolves to a string 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 declare function getUnits(type: string): Promise<string>;

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

@@ -9,19 +9,57 @@ import { CalculationRequest } from "../interfaces/Api";
  *
  * @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 declare function calculate(payload: CalculationRequest): Promise<string>;
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const types = await getTypes();
+ */
+export declare function getTypes(): Promise<string>;
+/**
+ * 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
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const areas = await getArea();
+ */
+export declare function getArea(): Promise<string>;
+/**
+ * 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<string>} A promise that resolves to a string 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 declare function getUnits(type: string): Promise<string>;

package/docs/_sources/authentication.rst.txt

@@ -0,0 +1,164 @@
+==============
+Authentication
+==============
+
+Overview
+--------
+
+The IBM Envizi - Emissions API Node.js SDK uses OAuth 2.0 Bearer Tokens for authentication. This page explains the authentication process, options, and security best practices in detail.
+
+Authentication Methods
+----------------------
+
+The SDK provides two authentication methods:
+
+API Key Authentication (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This method automatically handles token generation and refreshing:
+
+.. code-block:: javascript
+
+    import { Client } from 'emissions-api-sdk';
+    
+    await Client.getClient({
+      apiKey: process.env.ENVIZI_API_KEY,
+      clientId: process.env.ENVIZI_CLIENT_ID,
+      orgId: process.env.ENVIZI_ORG_ID
+    });
+
+**Required parameters:**
+    - ``apiKey``: Your API key for authentication
+    - ``clientId``: Your client identifier
+    - ``orgId``: Your organization identifier
+
+Token retrieval
+^^^^^^^^^^^^^^^
+When you call ``Client.getClient()`` with ``apiKey``:
+
+- **Method**: ``GET`` to the token endpoint (default: ``https://api.ibm.com/saascore/run/authentication-retrieve/api-key``)
+- **Headers**:
+  - ``X-Api-Key: <apiKey>``
+  - ``X-IBM-Client-Id: saascore-<clientId>``
+  - ``Accept: application/json``
+- **Query param**: ``orgId=<orgId>``
+- **Response**: a bearer token (string) which the SDK trims, caches, and uses for API calls.
+
+Pre-generated Token Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For scenarios where token generation is handled externally:
+
+.. code-block:: javascript
+
+    import { Client } from 'emissions-api-sdk';
+    
+    await Client.getClient({
+      token: process.env.JWT_TOKEN,
+      clientId: process.env.ENVIZI_CLIENT_ID
+    });
+
+**Required parameters:**
+    - ``token``: A pre-generated authentication token
+    - ``clientId``: Your client identifier
+
+Token lifetime & refresh
+^^^^^^^^^^^^^^^^^^^^^^^^
+- The SDK decodes the JWT’s ``exp`` and stores it.
+- In user-provided token mode, no refresh occurs; re-initialize with a fresh token when needed.
+
+Authentication Flow
+-------------------
+
+The authentication process follows these steps:
+
+1. **Initialization**:
+    - User provides authentication credentials
+    - Client validates the credentials format
+
+2. **Token Generation** (API Key method):
+    - Client sends API key to authentication service
+    - Authentication service validates credentials
+    - Authentication service returns a token with expiration time
+    - Client stores the token securely
+
+3. **Token Validation**:
+    - Before each API request, token validity is checked
+    - If valid, the token is included in the request
+    - If expired or near expiration, token is refreshed
+
+4. **Token Refreshing**:
+    - Client detects when token is approaching expiration
+    - Client automatically requests a new token
+    - New token replaces the old one for future requests
+
+Authentication Headers
+----------------------
+
+The SDK automatically includes the necessary headers for authentication:
+
+For token generation:
+    - ``X-Api-Key``: Your API key
+    - ``X-IBM-Client-Id``: saascore-{your-client-id}
+
+For API requests:
+    - ``Authorization``: Bearer {token}
+    - ``X-IBM-Client-Id``: ghgemissions-{your-client-id}
+    - ``X-Client-Source``: node-sdk
+
+Architecture Diagram
+--------------------
+
+::
+
+    +-----------------+          +-------------------------+
+    | Your application|          |   Token Service (GET)   |
+    |  (init once)    |          |  authUrl / default URL  |
+    +--------+--------+          +-----------+-------------+
+             |                                ^
+             | getClient({apiKey, clientId,   |  (managed mode only:
+             | orgId, [authUrl], [host]})     |   X-Api-Key, saascore-Client-Id,
+             v                                |   orgId => returns JWT)
+    +--------+--------------------------------+-------------+
+    |                   Client (singleton)                  |
+    |  - token, exp, domain, clientId                       |
+    |  - refresh before expiry (managed mode)               |
+    +--------+--------------------------------+-------------+
+             |                                ^
+             | makeApiRequest(...)            |
+             v                                |
+    +--------+--------------------------------+-------------+
+    |                 Request layer (axios)                 |
+    |  Adds headers:                                        |
+    |   - Authorization: Bearer <token>                     |
+    |   - X-IBM-Client-Id: ghgemissions-<clientId>          |
+    |   - X-Client-Source: excel | node-sdk                 |
+    +--------+--------------------------------+-------------+
+             |
+             v
+    +--------+--------------------------------+-------------+
+    |               Emissions API (host/domain)             |
+    +-------------------------------------------------------+
+
+
+Security Best Practices
+-----------------------
+
+1. **Use environment variables** for credentials:
+
+   .. code-block:: javascript
+
+       await Client.getClient({
+         apiKey: process.env.ENVIZI_API_KEY,
+         clientId: process.env.ENVIZI_CLIENT_ID,
+         orgId: process.env.ENVIZI_ORG_ID
+       });
+
+2. **Never hardcode** credentials in your application code
+3. **Implement proper access controls** for API keys
+4. **Use secure environment variables** for production deployments
+5. **Implement least privilege** principles for API access
+
+
+For more information about the Client that manages authentication, see the :doc:`client` page.
+

package/docs/_sources/client.rst.txt

@@ -0,0 +1,137 @@
+======
+Client
+======
+
+Overview
+--------
+
+The Client is the central component of the IBM Envizi - Emissions API Node.js SDK. It handles authentication, maintains connections to the API, and provides a unified interface for all API operations.
+
+.. code-block:: none
+
+   +----------------------+
+   | Application          |<-----------+
+   +----------------------+            |
+            |                          |
+            v                          |
+   +----------------------+            |
+   | Client               |<-----------+
+   +----------------------+            |
+            |                          |
+            v                          |
+   +----------------------+     +----------------------+
+   | Authentication       |---->| API Module Requests  |
+   +----------------------+     +----------------------+
+
+Client Initialization
+---------------------
+
+The Client is designed as a singleton to ensure consistent authentication across your application. Initialize it once at application startup:
+
+1. Managed token (SDK fetches & refreshes)
+
+.. code-block:: javascript
+
+    import { Client } from 'emissions-api-sdk';
+    
+    await Client.getClient({
+      apiKey:   process.env.ENVIZI_API_KEY,
+      clientId: process.env.ENVIZI_CLIENT_ID,
+      orgId:    process.env.ENVIZI_ORG_ID
+    });
+
+2. User-provided token (SDK will **not** refresh it)
+
+.. code-block:: javascript
+
+    import { Client } from "emissions-api-sdk";
+
+    await Client.getClient({
+      clientId: process.env.ENVIZI_CLIENT_ID,
+      token:    process.env.TOKEN
+    });
+
+Configuration Options
+---------------------
+
+The Client accepts the following configuration parameters:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 15 65
+
+   * - Parameter
+     - Required
+     - Description
+   * - apiKey
+     - Yes*
+     - API key for authentication (required unless using token)
+   * - clientId
+     - Yes
+     - Client ID for API access
+   * - orgId
+     - Yes*
+     - Organization ID (required with apiKey)
+   * - token
+     - Yes*
+     - Pre-generated token (required if not using apiKey)
+   * - host
+     - No
+     - Custom API endpoint (defaults to production)
+   * - authUrl
+     - No
+     - Custom authentication endpoint (defaults to production)
+
+.. note::
+    Either ``apiKey+orgId`` OR ``token`` is required
+
+Client Responsibilities
+-----------------------
+
+The Client handles several key responsibilities:
+
+1. **Singleton Management**: Ensures only one Client instance exists
+2. **Configuration Validation**: Verifies required parameters
+3. **Token Generation**: Obtains tokens from the authentication service
+4. **Token Refreshing**: Automatically refreshes tokens before expiration
+5. **Request Authentication**: Adds proper headers to all API requests
+
+Error Handling
+--------------
+
+Handle authentication errors gracefully:
+
+.. code-block:: javascript
+
+    try {
+      await Client.getClient({
+        apiKey: process.env.ENVIZI_API_KEY,
+        clientId: process.env.ENVIZI_CLIENT_ID,
+        orgId: process.env.ENVIZI_ORG_ID
+      });
+    } catch (error) {
+      console.error("Authentication error:", error.message);
+      // Implement appropriate error handling
+      if (error.response) {
+        // Handle specific HTTP error responses
+        console.error("Status:", error.response.status);
+        console.error("Details:", error.response.data);
+      }
+    }
+
+
+Best Practices
+--------------
+
+For optimal Client usage:
+
+1. **Initialize once** at application startup
+2. **Store credentials securely** using environment variables
+3. **Implement proper error handling** for authentication failures
+4. **Let the SDK handle** token refreshing automatically
+5. **Reuse the Client instance** across your application
+
+Authentication Integration
+--------------------------
+
+The Client works closely with the Authentication module to manage tokens. For detailed information about the authentication process, supported methods, and security best practices, see the :doc:`authentication` page.

package/docs/_sources/getting_started.rst.txt

@@ -0,0 +1,164 @@
+===============
+Getting Started
+===============
+
+Prerequisites
+-------------
+
+Before using the SDK, ensure you have:
+
+- **Node.js** installed
+- Active internet connection
+- Sign up for the preview waitlist `IBMid sign up <https://www.ibm.com/account/reg/us-en/signup?formid=urx-53659>`_ page.
+- API credentials (``apiKey``, ``tenantId``, ``orgId``), are available on the Emissions API `Overview Page <https://www-dev.supply-chain.ibm.com/envizi/emissions-api-home/overview?cuiURL=%2Femissions-api-home%2Foverview>`_ after sign up
+
+
+Installation
+------------
+
+You can install the SDK using `npm <https://www.npmjs.com/package/emissions-api-sdk>`_ or `yarn <https://yarnpkg.com/package?q=emissions-api-sdk&name=emissions-api-sdk>`_:
+
+Using npm:
+
+.. code-block:: bash
+
+  npm install emissions-api-sdk
+
+
+Using yarn:
+
+.. code-block:: bash
+
+  yarn install emissions-api-sdk
+
+
+Basic Import
+~~~~~~~~~~~~
+
+After installation, you can import the SDK in your project:
+
+.. code-block:: javascript
+
+  // Import the entire SDK
+  const enviziSDK = require('emissions-api-sdk');
+  
+  // Or using ES modules
+  import { Client, LocationEmission } from 'emissions-api-sdk';
+
+
+Authentication
+--------------
+
+Initialize the client with your API credentials:
+
+The SDK provides two authentication methods:
+
+- Using an **API key** with following required Headers:
+    - ``X-Api-Key``: Your API key
+    - ``X-IBM-Client-Id``: saascore-{your-client-id}
+    - ``accept``: application/json
+
+- Using a **Pre-generated token**
+    - Token Generation Endpoint: https://api.ibm.com/saascore/run/authentication-retrieve/api-key
+
+Using API Key (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: javascript
+
+  import { Client } from 'emissions-api-sdk';
+  
+  async function initialize() {
+    try {
+      await Client.getClient({
+        apiKey: "your-api-key",
+        clientId: "your-client-id",
+        orgId: "your-org-id"
+      });
+      console.log("Client initialized successfully");
+    } catch (error) {
+      console.error("Failed to initialize client:", error);
+    }
+  }
+  
+  initialize();
+
+Using Pre-generated Token
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you already have a token, you can use it directly:
+
+.. code-block:: javascript
+
+  import { Client } from 'emissions-api-sdk';
+
+  async function initialize() {
+    try {
+      await Client.getClient({
+        token: "your-pre-generated-token",
+        clientId: "your-client-id"
+      });
+      console.log("Client initialized successfully");
+    } catch (error) {
+      console.error("Failed to initialize client:", error);
+    }
+  }
+  
+  initialize();  
+
+First API Call
+--------------
+
+After initializing the client, you can make your first API call. Here's an example of calculating location-based emissions:
+
+.. code-block:: javascript
+
+  import { Client, LocationEmission } from 'emissions-api-sdk';
+  
+  async function calculateEmissions() {
+    try {
+      // Initialize client
+      await Client.getClient({
+        apiKey: "your-api-key",
+        clientId: "your-client-id",
+        orgId: "your-org-id"
+      });
+  
+      // Make API call
+      const result = await LocationEmission.calculate({
+        "location": {
+          "country": "USA",
+          "stateProvince": "california"
+        },
+        "activity": {
+          "type": "electricity",
+          "value": 1,
+          "unit": "kWh"
+        }
+      });
+      
+      console.log("Emission calculation result:", result);
+    } catch (error) {
+      console.error("Error calculating emissions:", error);
+    }
+  }
+  
+  calculateEmissions();
+
+Example Response
+----------------
+
+The API returns emission calculation results in JSON format. Here's an example response:
+
+.. code-block:: json
+
+    {
+      "transactionId": "95a7efe7-02ae-47a3-a7fd-831bfca7cecd",
+      "totalCO2e": 0.20750174,
+      "CO2": 0.20681091,
+      "CH4": 0.00033022,
+      "N2O": 0.00036061,
+      "indirectCO2e": 0.01115131,
+      "unit": "kgCO2e",
+      "description": "The electricity emissions factor used to calculate this result was obtained from the  year 2022 Managed - eGRID & US Climate Leaders factor set for the area United States and the region California."
+    }

package/docs/_sources/index.rst.txt

@@ -0,0 +1,29 @@
+IBM Envizi - Emissions API Node.js SDK
+======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   getting_started
+   sdk
+   reference
+
+Introduction
+============
+
+IBM Envizi - Emissions API (Emissions API) is a managed factor database and calculation engine for embedding greenhouse gas (GHG) emissions calculations into operational decision making.
+
+The **emissions-api-sdk** is a Node.js SDK for using Emissions API in your projects.
+
+Supported Emission Types
+------------------------
+
+* **Location** – emissions from region-specific factors  
+* **Fugitive** – emissions from leaks or fugitive sources  
+* **Mobile** – emissions from vehicles and mobile equipment  
+* **Stationary** – emissions from fixed fuel consumption  
+* **Transportation & distribution** – logistics and supply chain activities  
+* **Generic** – custom emission calculations  
+
+The SDK is designed for embedding emission calculations in applications, building sustainability dashboards, automating large-scale datasets, and tracking carbon footprints.