emissions-api-sdk 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emissions-api-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "sdk for IBM Emissions APIs",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",

package/sphinx-build/Makefile

@@ -0,0 +1,49 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   := sphinx-build
+SOURCEDIR     := source
+BUILDDIR      := build
+DOCS_DIR      := ../docs
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Clean build directory
+.PHONY: clean
+clean:
+	@echo "Cleaning build directory..."
+	@rm -rf $(BUILDDIR)
+	@echo "Done."
+
+# Build HTML documentation
+.PHONY: html
+html:
+	@echo "Building HTML documentation..."
+	@$(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html
+	@echo "Done. Output is in $(BUILDDIR)/html"
+
+# Clean and build HTML
+.PHONY: all
+all: clean html
+	@echo "Documentation build complete."
+
+# Copy built HTML to docs directory for GitHub Pages
+.PHONY: pages
+pages: all
+	@echo "Copying documentation to docs directory..."
+	@rm -rf $(DOCS_DIR)/*
+	@mkdir -p $(DOCS_DIR)
+	@cp -r $(BUILDDIR)/html/* $(DOCS_DIR)/
+	@echo "Done. GitHub Pages content is in $(DOCS_DIR)"

package/sphinx-build/requirements.txt

@@ -0,0 +1,5 @@
+sphinx==8.1.3
+furo==2025.7.19
+nbsphinx==0.9.7
+sphinxcontrib-httpdomain==1.8.1
+pandoc

package/sphinx-build/source/_static/custom.css

@@ -0,0 +1,16 @@
+div.nbinput.container div.input_area {
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    background: #f8f8f8;
+}
+
+div.nboutput.container div.output_area {
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    background: #fcfcfc;
+}
+
+/* Make code cells more readable */
+.highlight {
+    background: #f8f8f8;
+}

package/sphinx-build/source/authentication.rst

@@ -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/sphinx-build/source/client.rst

@@ -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/sphinx-build/source/conf.py

@@ -0,0 +1,56 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'IBM Envizi - Emissions API Node.js SDK'
+copyright = '2025, IBM Corporation'
+author = 'Ridham Thumar'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
+
+# Language used for content
+language = 'en'
+
+# Source file suffix
+source_suffix = {
+    '.rst': 'restructuredtext',
+}
+
+# The master document
+master_doc = 'index'
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx_js'
+]
+
+js_language = 'typescript'
+
+js_source_path = '../../src'
+
+primary_domain = 'js'
+
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']
+
+# Add CSS to improve notebook appearance
+html_css_files = [
+    'custom.css',
+]

package/sphinx-build/source/getting_started.rst

@@ -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/sphinx-build/source/index.rst

@@ -0,0 +1,30 @@
+IBM Envizi - Emissions API Node.js SDK
+======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   getting_started
+   sdk
+   reference
+   troubleshooting
+
+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.