emissions-api-sdk 1.0.1 → 1.0.3

package/package.json

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

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/index.rst

@@ -8,6 +8,7 @@ IBM Envizi - Emissions API Node.js SDK
    getting_started
    sdk
    reference
+   troubleshooting
 
 Introduction
 ============

package/sphinx-build/source/reference.rst

@@ -83,6 +83,12 @@ getUnits
 
 .. js:autofunction:: Fugitive.getUnits
 
+
+Usage API
+===========
+
+.. js:autofunction:: Usage.getUsage
+
 Interfaces
 ==========
 

package/sphinx-build/source/troubleshooting.rst

@@ -0,0 +1,486 @@
+Troubleshooting Guide
+=====================
+
+Overview
+--------
+
+This document lists all SDK-specific errors that can occur when using the Emissions API Node.js SDK. These errors are related to SDK initialization and client management.
+
+----
+
+SDK Initialization Errors
+--------------------------
+
+Configuration Errors
+~~~~~~~~~~~~~~~~~~~~
+
+These errors occur when ``Client.getClient()`` is called with invalid or missing configuration parameters.
+
+1. Missing Auth URL with Custom Host
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Error Message:**
+
+.. code-block:: text
+
+   Error: If custom "host" is provided, "authUrl" must also be provided.
+
+**Cause:** Custom host URL provided without corresponding authentication URL
+
+**Solution:** Provide both ``host`` and ``authUrl`` parameters together
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     host: 'https://api.ibm.com',
+     clientId: 'client123',
+     orgId: 'org456'
+     // Missing authUrl parameter
+   });
+
+----
+
+2. Missing Client ID with Token
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Error Message:**
+
+.. code-block:: text
+
+   Error: If token is provided directly, "clientId" must also be provided.
+
+**Cause:** Pre-existing token provided without client ID
+
+**Solution:** Provide ``clientId`` parameter when using a token
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     token: 'your-jwt-token'
+     // Missing clientId parameter
+   });
+
+----
+
+3. Missing Parameters with API Key
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Error Message:**
+
+.. code-block:: text
+
+   Error: If apiKey is provided , "clientId" and "OrgId" must also be provided.
+
+**Cause:** API key authentication requires both client ID and organization ID
+
+**Solution:** Provide ``apiKey``, ``clientId``, and ``orgId`` parameters together
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   // Missing orgId
+   await Client.getClient({
+     apiKey: 'your-api-key',
+     clientId: 'client123'
+     // Missing orgId parameter
+   });
+
+   // Or missing clientId
+   await Client.getClient({
+     apiKey: 'your-api-key',
+     orgId: 'org456'
+     // Missing clientId parameter
+   });
+
+----
+
+Authentication Errors (HTTP 401)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These errors occur when authentication credentials are invalid or expired.
+
+4. Invalid API Key
+^^^^^^^^^^^^^^^^^^
+
+**Error Response:**
+
+.. code-block:: json
+
+   {
+     "httpCode": "401",
+     "httpMessage": "Unauthorized",
+     "moreInformation": "Cannot pass the security checks that are required by the target API or operation, Enable debug headers for more details."
+   }
+
+**Cause:** API key is invalid, expired, or revoked
+
+**Solution:** Verify API key from IBM Cloud console and ensure it has proper permissions
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     apiKey: 'invalid_api_key_12345',
+     clientId: 'client123',
+     orgId: 'org456',
+     host: 'https://api.ibm.com',
+     authUrl: 'https://api.ibm.com/auth-url'
+   });
+
+----
+
+5. Invalid Organization ID
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Error Response:**
+
+.. code-block:: json
+
+   {
+     "httpCode": "401",
+     "httpMessage": "Unauthorized",
+     "moreInformation": "Cannot pass the security checks that are required by the target API or operation, Enable debug headers for more details."
+   }
+
+**Cause:** Organization ID doesn't match account or user lacks access
+
+**Solution:** Verify organization ID from IBM Cloud account settings
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     apiKey: 'your-valid-api-key',
+     clientId: 'client123',
+     orgId: 'invalid-org-id-12345',
+     host: 'https://api.ibm.com',
+     authUrl: 'https://api.ibm.com/auth-url'
+   });
+
+----
+
+6. Invalid Client ID
+^^^^^^^^^^^^^^^^^^^^^
+
+**Error Response:**
+
+.. code-block:: json
+
+   {
+     "httpCode": "401",
+     "httpMessage": "Unauthorized",
+     "moreInformation": "Invalid client id or secret."
+   }
+
+**Cause:** Client ID is invalid or doesn't match credentials
+
+**Solution:** Verify client ID from IBM Cloud credentials
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     apiKey: 'your-valid-api-key',
+     clientId: 'invalid-client-id-12345',
+     orgId: 'org456',
+     host: 'https://api.ibm.com',
+     authUrl: 'https://api.ibm.com/auth-url'
+   });
+
+----
+
+7. Empty Token Response
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Error Message:**
+
+.. code-block:: text
+
+   Error: Token response is empty
+
+**Cause:** Authentication server returned an empty or null token in the response body
+
+**Solution:**
+
+- Verify the ``authUrl`` is correct and points to a valid authentication endpoint
+- Ensure the authentication service is responding correctly
+- Check that the API key, client ID, and org ID combination is valid
+- Verify the authentication endpoint is returning a token in the response
+- Contact support if the authentication service is not responding properly
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     apiKey: 'your-api-key',
+     clientId: 'client123',
+     orgId: 'org456',
+     host: 'https://api.ibm.com/',
+     authUrl: 'https://valid-url-but-returns-empty-token.example.com/token'
+     // Valid URL but returns empty token in response
+   });
+
+**Note:** If the authUrl is completely invalid or unreachable (e.g., wrong domain), you'll get a network error (ENOTFOUND) instead of this error. This error specifically occurs when the authentication endpoint responds but returns an empty token.
+
+----
+
+8. Missing Expiry Field in Token
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Error Message:**
+
+.. code-block:: text
+
+   Error: exp field is missing in the token
+
+**Cause:** The provided JWT token does not contain the required ``exp`` (expiry) field
+
+**Solution:**
+
+- Ensure the token is a valid JWT with an expiry field
+- Regenerate the token if it's malformed
+- Verify the token was generated correctly by the authentication service
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     token: 'malformed-jwt-token-without-exp-field',
+     clientId: 'client123'
+   });
+
+**Note:** This error occurs when using token-based authentication with a JWT that doesn't include the standard ``exp`` (expiration time) claim.
+
+----
+
+Client Instance Errors
+-----------------------
+
+Client Not Initialized
+~~~~~~~~~~~~~~~~~~~~~~
+
+**Error Message:**
+
+.. code-block:: text
+
+   Error: Client is not initialized. Call Client.getClient() first.
+
+**Cause:** Attempting to use ``Client.getInstance()`` or API methods before calling ``Client.getClient()``
+
+**Solution:** Always call ``Client.getClient()`` before using any SDK methods
+
+**When This Occurs:**
+
+- Calling ``Client.getInstance()`` before initialization
+- Calling any API method (Stationary.calculate(), Mobile.calculate(), etc.) before initialization
+- Application restart without re-initializing the client
+
+**Sample Function Calls That Cause This Error:**
+
+.. code-block:: typescript
+
+   // Error 1: Calling getInstance() before initialization
+   const client = Client.getInstance(); // Throws error
+
+   // Error 2: Calling API methods before initialization
+   await Stationary.calculate({
+     time: { date: "2025-01-04" },
+     location: { country: "usa" },
+     activity: { type: "Coal - Lignite", unit: "KJ", value: 3 }
+   }); // Throws error
+
+   // Error 3: Calling any other API method
+   await Mobile.calculate({...}); // Throws error
+   await Fugitive.calculate({...}); // Throws error
+   await Location.getUnits("steam"); // Throws error
+
+----
+
+Token Management
+----------------
+
+Automatic Token Refresh
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The SDK automatically refreshes authentication tokens when they are about to expire (within 60 seconds). Token refresh failures will cause subsequent API calls to fail with 401 errors.
+
+**Note:** Token refresh only occurs for tokens generated by the SDK, not for user-provided tokens.
+
+----
+
+Error Summary Table
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 10 30
+
+   * - Error Type
+     - Error Message
+     - HTTP Code
+     - Solution
+   * - Configuration
+     - ``If custom "host" is provided, "authUrl" must also be provided.``
+     - N/A
+     - Provide both host and authUrl
+   * - Configuration
+     - ``If token is provided directly, "clientId" must also be provided.``
+     - N/A
+     - Provide clientId with token
+   * - Configuration
+     - ``If apiKey is provided , "clientId" and "OrgId" must also be provided.``
+     - N/A
+     - Provide all three parameters
+   * - Authentication
+     - ``Cannot pass the security checks...``
+     - 401
+     - Verify API key and org ID
+   * - Authentication
+     - ``Invalid client id or secret``
+     - 401
+     - Verify client ID
+   * - Authentication
+     - ``Token response is empty``
+     - N/A
+     - Check network and authUrl
+   * - Token
+     - ``exp field is missing in the token``
+     - N/A
+     - Use valid JWT with exp field
+   * - Instance
+     - ``Client is not initialized. Call Client.getClient() first.``
+     - N/A
+     - Call getClient() first
+
+----
+
+Required Configuration Parameters
+----------------------------------
+
+When calling ``Client.getClient()``, the following parameters are required based on authentication method:
+
+API Key Authentication (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``apiKey`` - Your IBM Cloud API key
+- ``clientId`` - Your client ID
+- ``orgId`` - Your organization ID
+- ``host`` - API host URL
+- ``authUrl`` - Authentication URL
+
+Token Authentication
+~~~~~~~~~~~~~~~~~~~~
+
+- ``token`` - Pre-existing JWT token
+- ``clientId`` - Your client ID
+
+----
+
+Initialization Checklist
+-------------------------
+
+Before using the SDK, ensure:
+
+- [ ] All required configuration parameters are provided
+- [ ] Credentials are valid and not expired
+- [ ] Correct environment URLs are used
+- [ ] ``Client.getClient()`` is called before any API methods
+- [ ] Error handling is implemented for initialization failures
+- [ ] Credentials are stored securely (environment variables recommended)
+
+----
+
+Common Scenarios
+----------------
+
+Scenario 1: Application Startup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Issue:** SDK must be initialized when application starts
+
+**Solution:** Call ``Client.getClient()`` in application initialization code before using any API methods
+
+Scenario 2: Invalid Credentials
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Issue:** 401 Unauthorized errors during initialization
+
+**Solution:** Verify all credentials (API key, client ID, org ID) from IBM Cloud console
+
+Scenario 3: Missing Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Issue:** Configuration error thrown before API call
+
+**Solution:** Ensure all required parameters are provided based on authentication method
+
+Scenario 4: Client Not Initialized
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Issue:** Error when calling API methods
+
+**Solution:** Verify ``Client.getClient()`` was called successfully before using API methods
+
+----
+
+Troubleshooting Steps
+----------------------
+
+1. **Verify Configuration**
+
+   - Check all required parameters are provided
+   - Ensure no parameters are empty or null
+   - Verify host and authUrl match your environment
+
+2. **Verify Credentials**
+
+   - Confirm API key is valid and not expired
+   - Check organization ID matches your IBM Cloud account
+   - Verify client ID is correct
+
+3. **Check Initialization**
+
+   - Ensure ``Client.getClient()`` is called before API methods
+   - Verify initialization completed without errors
+   - Check for any error messages during initialization
+
+4. **Network and Service**
+
+   - Verify network connectivity
+   - Check authentication service availability
+   - Ensure firewall allows connections to IBM Cloud
+
+----
+
+Support
+-------
+
+For issues not covered in this guide:
+
+1. Verify SDK version is up to date
+2. Check IBM Cloud service status
+3. Review error messages and HTTP status codes
+4. Contact IBM Support with:
+
+   - Error message and stack trace
+   - SDK version
+   - Environment details
+   - Steps to reproduce (excluding sensitive credentials)
+
+----
+
+**Last Updated:** 2025-11-24
+
+**SDK Version:** 1.0.1
+
+**Coverage:** SDK initialization, client instance, and authentication errors

package/src/Constants.ts

@@ -35,6 +35,8 @@ export const GENERAL_API_UNITS = "/v3/carbon/calculation/units";
 export const FACTOR_API_UNITS = "/v3/carbon/factor/units";
 export const TRANSPORTATION_AND_DISTRIBUTION_API_UNITS = "/v3/carbon/transportation-and-distribution/units";
 
+export const USAGE_API = "/v3/carbon/usage";
+
 export const GET = "GET";
 export const POST = "POST";
 export const CLIENT_SOURCE_HEADER = "X-Client-Source";

package/src/api/Calculation.ts

@@ -1,17 +1,22 @@
 import { Client } from "../Client";
 import { GENERIC_CALCULATION_API_PATH,CALCULATION_TYPES, POST, GET, GENERAL_API_AREA, GENERAL_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 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
+ * @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 calculationRequest = {
     "time" : {
@@ -32,11 +37,11 @@ import { makeApiRequest } from "../request";
  */
 export async function calculate(
   payload: CalculationRequest
-): Promise<string> {
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
   const client = Client.getInstance();
   const url = client.getDomain() + GENERIC_CALCULATION_API_PATH;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
     method: POST,
     url,
     data: payload,
@@ -48,17 +53,17 @@ export async function calculate(
  * Retrieves available calculation types by making a GET request to the calculation types API endpoint.
  *
  * @export
- * @return {Promise<string>} A promise that resolves to a string containing the available calculation types
+ * @return {Promise<TypeResponse>} A promise that resolves to a TypeResponse containing the available calculation types
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
  * const types = await getTypes();
  */
-export async function getTypes(): Promise<string> {
+export async function getTypes(): Promise<TypeResponse> {
   const client = Client.getInstance();
   const url = client.getDomain() + CALCULATION_TYPES;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<TypeResponse>({
     method: GET,
     url
   });
@@ -68,17 +73,17 @@ export async function getTypes(): Promise<string> {
  * Retrieves information about geographical areas supported by the calculation 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> {
+export async function getArea(): Promise<AreaResponse> {
   const client = Client.getInstance();
   const url = client.getDomain() + GENERAL_API_AREA;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<AreaResponse>({
     method: GET,
     url
   });
@@ -89,7 +94,7 @@ export async function getArea(): Promise<string> {
  *
  * @export
  * @param {string} type - The calculation type to get units for
- * @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
@@ -101,11 +106,11 @@ export async function getArea(): Promise<string> {
  */
 export async function getUnits(
   type: string
-): Promise<string> {
+): Promise<UnitResponse> {
   const client = Client.getInstance();
   const url = client.getDomain() + GENERAL_API_UNITS;
 
-  return makeApiRequest<string>({
+  return makeApiRequest<UnitResponse>({
     method: GET,
     url,
     params : { type }