emissions-api-sdk 1.0.11 → 1.0.13

package/sphinx-build/source/getting_started.rst

@@ -9,8 +9,9 @@ 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
+- An IBMid account. Sign up at the `IBMid sign up <https://www.ibm.com/account/reg/us-en/signup?formid=urx-54311>`_ page.
+- Access to the Emissions API service and the required credentials
+- Read the `Introduction <https://developer.ibm.com/apis/catalog/ghgemissions--ibm-envizi-emissions-api/Introduction>`_ page for an overview of the Emissions API
 
 
 Installation
@@ -49,101 +50,78 @@ After installation, you can import the SDK in your project:
 Authentication
 --------------
 
-Initialize the client with your API credentials:
+The SDK supports three authentication methods:
 
-The SDK provides two authentication methods:
+- **Personal Access Token (PAT)**, recommended for most users
+- **API key**, where the SDK retrieves and refreshes a bearer token
+- **Pre-generated JWT token**, managed outside the SDK
 
-- 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 Personal Access Token (PAT)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Using a **Pre-generated token**
-    - Token Generation Endpoint: https://api.ibm.com/saascore/run/authentication-retrieve/api-key
+.. code-block:: javascript
 
-Using API Key (Recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  import { Client } from 'emissions-api-sdk';
+
+  await Client.getClient({
+    patToken: process.env.ENVIZI_PAT_TOKEN,
+    clientId: process.env.ENVIZI_CLIENT_ID
+  });
+
+.. note::
+
+   When using a PAT token, do not provide ``orgId``.
+
+Using API Key
+~~~~~~~~~~~~~
 
 .. 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
-~~~~~~~~~~~~~~~~~~~~~~~~~
+  await Client.getClient({
+    apiKey: process.env.ENVIZI_API_KEY,
+    clientId: process.env.ENVIZI_CLIENT_ID,
+    orgId: process.env.ENVIZI_ORG_ID
+  });
 
-If you already have a token, you can use it directly:
+Using Pre-generated JWT Token
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. 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();  
+  await Client.getClient({
+    token: process.env.JWT_TOKEN,
+    clientId: process.env.ENVIZI_CLIENT_ID
+  });
 
 First API Call
 --------------
 
-After initializing the client, you can make your first API call. Here's an example of calculating location-based emissions:
+After initializing the client, you can make your first API call. Here's a quick start 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);
+  import { Client, Location } from 'emissions-api-sdk';
+
+  await Client.getClient({
+    patToken: process.env.ENVIZI_PAT_TOKEN,
+    clientId: process.env.ENVIZI_CLIENT_ID
+  });
+
+  const result = await Location.calculate({
+    "location": {
+      "country": "USA",
+      "stateProvince": "california"
+    },
+    "activity": {
+      "type": "electricity",
+      "value": 1,
+      "unit": "kWh"
     }
-  }
-  
-  calculateEmissions();
+  });
 
 Example Response
 ----------------
@@ -162,3 +140,489 @@ The API returns emission calculation results in JSON format. Here's an example r
       "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."
     }
+
+Example Response with Details
+------------------------------
+
+When you need more detailed information about the emission factors used in calculations, you can request the response to include the ``details`` object. This provides comprehensive information about the factor set and specific factor used:
+
+.. code-block:: json
+
+    {
+      "transactionId": "29df5ecd-fc3b-4797-b6fd-da03bc007f30",
+      "totalCO2e": 5912000,
+      "CO2": 5840000,
+      "CH4": 2000.0000000000002,
+      "N2O": 70000,
+      "indirectCO2e": 1340000,
+      "unit": "kgCO2e",
+      "description": "The Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt emissions factor used to calculate this result was obtained from the DEFRA factor set for the Global region year 2025.",
+      "details": {
+        "factorSet": {
+          "name": "DEFRA",
+          "description": "The UK Government and DEFRA publish GHG emission factors covering Scope 1, Scope 2, and selected Scope 3 sources. While primarily intended for UK-based reporting, many organizations apply these factors across European sites—especially for air travel-related emissions.",
+          "provider": "His Majesty's Government (United Kingdom of Great Britain and Northern Ireland): Department for Energy Security and Net Zero",
+          "sourceUrl": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2024"
+        },
+        "factor": {
+          "name": "Bulk carrier - 0–9999 dwt - 2025",
+          "description": "Cargo ship - tonne.km",
+          "totalCO2e": 0.02956,
+          "CO2": 0.0292,
+          "CH4": 0.00001,
+          "N2O": 0.00035,
+          "indirectCO2e": 0.0067,
+          "inputUnit": "t-km",
+          "unit": "tonne.km",
+          "conversionRatio": "1:1",
+          "activityType": "Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt",
+          "activitySubtype": "Default Factor",
+          "factorId": 190405,
+          "methodology": "activity-based",
+          "scopes": [
+            "3.4",
+            "3.9"
+          ],
+          "areaName": "Earth",
+          "areaType": "Planet",
+          "publishedFrom": "2025-01-01",
+          "source": "2025 Greenhouse Gas Reporting: Conversion Factors 2025 (DEFRA) provided by gov.uk, license - https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
+        }
+      }
+    }
+
+Response Structure Details
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The response includes the following key components:
+
+**Top-level Fields:**
+
+- ``transactionId``: Unique identifier for the calculation
+- ``totalCO2e``: Total CO2 equivalent emissions
+- ``CO2``: Carbon dioxide emissions
+- ``CH4``: Methane emissions
+- ``N2O``: Nitrous oxide emissions
+- ``indirectCO2e``: Indirect CO2 equivalent emissions
+- ``unit``: Unit of measurement (typically kgCO2e)
+- ``description``: Human-readable description of the calculation
+
+**Details Object (when requested):**
+
+The ``details`` object provides comprehensive information about the emission factors:
+
+*Factor Set Information:*
+
+- ``name``: Name of the factor set (e.g., DEFRA, EPA)
+- ``description``: Detailed description of the factor set
+- ``provider``: Organization that provides the factor set
+- ``sourceUrl``: URL to the source documentation
+
+*Factor Information:*
+
+- ``name``: Specific name of the emission factor
+- ``description``: Description of the factor
+- ``totalCO2e``, ``CO2``, ``CH4``, ``N2O``, ``indirectCO2e``: Emission values per unit
+- ``inputUnit``: Unit for input values
+- ``unit``: Unit of the factor
+- ``conversionRatio``: Conversion ratio applied
+- ``activityType``: Type of activity (e.g., transportation, energy)
+- ``activitySubtype``: Subtype classification
+- ``factorId``: Unique identifier for the factor
+- ``methodology``: Calculation methodology used
+- ``scopes``: Applicable GHG Protocol scopes
+- ``areaName``: Geographic area name
+- ``areaType``: Type of geographic area
+- ``publishedFrom``: Date from which the factor is valid
+
+Currency Conversion Support
+---------------------------
+
+Overview
+~~~~~~~~
+
+The SDK supports automatic currency conversion for API methods that accept monetary values. This feature allows you to input values in your preferred currency, and the system will automatically convert them to the appropriate base currency for emissions calculations.
+
+**Supported Methods**
+
+Currency conversion is available for the following calculation methods:
+
+- ``EconomicActivity.calculate()``
+- ``RealEstate.calculate()``
+- ``PhysicalActivity.calculate()``
+
+Supported Currencies
+~~~~~~~~~~~~~~~~~~~~
+
+The SDK supports conversion for 170 currencies:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 60 40
+
+   * - Currency Name
+     - Symbol
+   * - ADB Unit of Account
+     - XUA
+   * - Afghani
+     - AFN
+   * - Algerian Dinar
+     - DZD
+   * - Arab Accounting Dinar
+     - XAD
+   * - Argentine Peso
+     - ARS
+   * - Armenian Dram
+     - AMD
+   * - Aruban Florin
+     - AWG
+   * - Australian Dollar
+     - AUD
+   * - Azerbaijan Manat
+     - AZN
+   * - Bahamian Dollar
+     - BSD
+   * - Bahraini Dinar
+     - BHD
+   * - Baht
+     - THB
+   * - Balboa
+     - PAB
+   * - Barbados Dollar
+     - BBD
+   * - Belarusian Ruble
+     - BYN
+   * - Belize Dollar
+     - BZD
+   * - Bermudian Dollar
+     - BMD
+   * - Boliviano
+     - BOB
+   * - Bolívar Soberano
+     - VED
+   * - Bolívar Soberano
+     - VES
+   * - Brazilian Real
+     - BRL
+   * - Brunei Dollar
+     - BND
+   * - Bulgarian Lev
+     - BGN
+   * - Burundi Franc
+     - BIF
+   * - Cabo Verde Escudo
+     - CVE
+   * - Canadian Dollar
+     - CAD
+   * - Caribbean Guilder
+     - XCG
+   * - Cayman Islands Dollar
+     - KYD
+   * - CFA Franc BCEAO
+     - XOF
+   * - CFA Franc BEAC
+     - XAF
+   * - CFP Franc
+     - XPF
+   * - Chilean Peso
+     - CLP
+   * - Colombian Peso
+     - COP
+   * - Comorian Franc
+     - KMF
+   * - Congolese Franc
+     - CDF
+   * - Convertible Mark
+     - BAM
+   * - Cordoba Oro
+     - NIO
+   * - Costa Rican Colon
+     - CRC
+   * - Cuban Peso
+     - CUP
+   * - Czech Koruna
+     - CZK
+   * - Dalasi
+     - GMD
+   * - Danish Krone
+     - DKK
+   * - Denar
+     - MKD
+   * - Djibouti Franc
+     - DJF
+   * - Dobra
+     - STN
+   * - Dominican Peso
+     - DOP
+   * - Dong
+     - VND
+   * - East Caribbean Dollar
+     - XCD
+   * - Egyptian Pound
+     - EGP
+   * - El Salvador Colon
+     - SVC
+   * - Ethiopian Birr
+     - ETB
+   * - Euro
+     - EUR
+   * - Falkland Islands Pound
+     - FKP
+   * - Fiji Dollar
+     - FJD
+   * - Forint
+     - HUF
+   * - Ghana Cedi
+     - GHS
+   * - Gibraltar Pound
+     - GIP
+   * - Gourde
+     - HTG
+   * - Guarani
+     - PYG
+   * - Guinean Franc
+     - GNF
+   * - Guyana Dollar
+     - GYD
+   * - Hong Kong Dollar
+     - HKD
+   * - Hryvnia
+     - UAH
+   * - Iceland Krona
+     - ISK
+   * - Indian Rupee
+     - INR
+   * - Iranian Rial
+     - IRR
+   * - Iraqi Dinar
+     - IQD
+   * - Jamaican Dollar
+     - JMD
+   * - Jordanian Dinar
+     - JOD
+   * - Kenyan Shilling
+     - KES
+   * - Kina
+     - PGK
+   * - Kuwaiti Dinar
+     - KWD
+   * - Kwanza
+     - AOA
+   * - Kyat
+     - MMK
+   * - Lao Kip
+     - LAK
+   * - Lari
+     - GEL
+   * - Lebanese Pound
+     - LBP
+   * - Lek
+     - ALL
+   * - Lempira
+     - HNL
+   * - Leone
+     - SLE
+   * - Liberian Dollar
+     - LRD
+   * - Libyan Dinar
+     - LYD
+   * - Lilangeni
+     - SZL
+   * - Loti
+     - LSL
+   * - Malagasy Ariary
+     - MGA
+   * - Malawi Kwacha
+     - MWK
+   * - Malaysian Ringgit
+     - MYR
+   * - Mauritius Rupee
+     - MUR
+   * - Mexican Peso
+     - MXN
+   * - Mexican Unidad de Inversion (UDI)
+     - MXV
+   * - Moldovan Leu
+     - MDL
+   * - Moroccan Dirham
+     - MAD
+   * - Mozambique Metical
+     - MZN
+   * - Mvdol
+     - BOV
+   * - Naira
+     - NGN
+   * - Nakfa
+     - ERN
+   * - Namibia Dollar
+     - NAD
+   * - Nepalese Rupee
+     - NPR
+   * - Netherlands Antillean Guilder
+     - ANG
+   * - New Israeli Sheqel
+     - ILS
+   * - New Taiwan Dollar
+     - TWD
+   * - New Zealand Dollar
+     - NZD
+   * - Ngultrum
+     - BTN
+   * - North Korean Won
+     - KPW
+   * - Norwegian Krone
+     - NOK
+   * - Ouguiya
+     - MRU
+   * - Pa'anga
+     - TOP
+   * - Pakistan Rupee
+     - PKR
+   * - Pataca
+     - MOP
+   * - Peso Uruguayo
+     - UYU
+   * - Philippine Peso
+     - PHP
+   * - Pound Sterling
+     - GBP
+   * - Pula
+     - BWP
+   * - Qatari Rial
+     - QAR
+   * - Quetzal
+     - GTQ
+   * - Rand
+     - ZAR
+   * - Rial Omani
+     - OMR
+   * - Riel
+     - KHR
+   * - Romanian Leu
+     - RON
+   * - Rufiyaa
+     - MVR
+   * - Rupiah
+     - IDR
+   * - Russian Ruble
+     - RUB
+   * - Rwanda Franc
+     - RWF
+   * - Saint Helena Pound
+     - SHP
+   * - Saudi Riyal
+     - SAR
+   * - SDR (Special Drawing Right)
+     - XDR
+   * - Serbian Dinar
+     - RSD
+   * - Seychelles Rupee
+     - SCR
+   * - Singapore Dollar
+     - SGD
+   * - Sol
+     - PEN
+   * - Solomon Islands Dollar
+     - SBD
+   * - Som
+     - KGS
+   * - Somali Shilling
+     - SOS
+   * - Somoni
+     - TJS
+   * - South Sudanese Pound
+     - SSP
+   * - Sri Lanka Rupee
+     - LKR
+   * - Sucre
+     - XSU
+   * - Sudanese Pound
+     - SDG
+   * - Surinam Dollar
+     - SRD
+   * - Swedish Krona
+     - SEK
+   * - Swiss Franc
+     - CHF
+   * - Syrian Pound
+     - SYP
+   * - Taka
+     - BDT
+   * - Tala
+     - WST
+   * - Tanzanian Shilling
+     - TZS
+   * - Tenge
+     - KZT
+   * - Trinidad and Tobago Dollar
+     - TTD
+   * - Tugrik
+     - MNT
+   * - Tunisian Dinar
+     - TND
+   * - Turkish Lira
+     - TRY
+   * - Turkmenistan New Manat
+     - TMT
+   * - UAE Dirham
+     - AED
+   * - Uganda Shilling
+     - UGX
+   * - Unidad de Fomento
+     - CLF
+   * - Unidad de Valor Real
+     - COU
+   * - Unidad Previsional
+     - UYW
+   * - United States dollar
+     - USD
+   * - Uruguay Peso en Unidades Indexadas (UI)
+     - UYI
+   * - US Dollar (Next day)
+     - USN
+   * - Uzbekistan Sum
+     - UZS
+   * - Vatu
+     - VUV
+   * - WIR Euro
+     - CHE
+   * - WIR Franc
+     - CHW
+   * - Won
+     - KRW
+   * - Yemeni Rial
+     - YER
+   * - Yen
+     - JPY
+   * - Yuan Renminbi
+     - CNY
+   * - Zambian Kwacha
+     - ZMW
+   * - Zimbabwe Gold
+     - ZWG
+   * - Zloty
+     - PLN
+
+Exchange Rate Data
+~~~~~~~~~~~~~~~~~~
+
+**Data Source**
+
+Exchange rates are sourced from the U.S. Department of the Treasury's Fiscal Data API, which provides official exchange rates used by the U.S. government for accounting and reporting purposes.
+
+- **API Source**: https://api.fiscaldata.treasury.gov/services/api/fiscal_service
+- **Data Provider**: U.S. Department of the Treasury, Bureau of the Fiscal Service
+
+**Historical Coverage**
+
+Exchange rate data is available from **March 31, 2001** onwards. If you specify a date earlier than this, the system will use the earliest available rate.
+
+**Data Updates**
+
+The exchange rate database is automatically synchronized with the Treasury API to ensure you always have access to the most current rates. Updates are captured as soon as they become available from the Treasury.
+
+- **Update Frequency**: The U.S. Treasury typically publishes exchange rates on a **quarterly basis**
+- **Amendment Policy**: If current rates deviate from the published rates by 10% or more, Treasury will issue amendments to the quarterly report
+
+
+- ``source``: Source citation and license information

package/sphinx-build/source/index.rst

@@ -7,6 +7,8 @@ IBM Envizi - Emissions API Node.js SDK
 
    getting_started
    sdk
+   authentication
+   client
    reference
    troubleshooting
 
@@ -30,3 +32,12 @@ Supported Emission Types
 * **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.
+
+Additional capabilities
+-----------------------
+
+* **Metadata API** – query supported types, areas, and units across endpoints
+* **Type Recommender API** – semantic search to identify likely activity types, with optional reranker control and scope in results
+* **Factor Search API** – search for emission factors with unit and scope filtering, with optional reranker control
+* **Usage API** – retrieve organization billing-period or historical usage
+* **Audit Log API** – manage whether API requests and responses are stored for auditing

package/sphinx-build/source/reference.rst

@@ -15,6 +15,8 @@ API
 
 .. js:autofunction:: Factor.retrieveFactor
 
+.. js:autofunction:: Factor.search
+
 .. js:autofunction:: Fugitive.calculate
 
 .. js:autofunction:: Calculation.calculate
@@ -31,6 +33,22 @@ API
 
 .. js:autofunction:: EconomicActivity.calculate
 
+Type Recommender API
+====================
+
+.. js:autofunction:: TypeRecommender.search
+
+
+Audit Log API
+=============
+
+Controls whether the organization's API requests and responses are stored for auditing.
+Organizations can disable storage if they don't need their API calls to be audited.
+
+.. js:autofunction:: AuditLog.getAuditConfig
+
+.. js:autofunction:: AuditLog.updateAuditConfig
+
 
 Global Metadata API
 ====================
@@ -113,3 +131,11 @@ Interfaces
 .. js:autoclass:: Config.RequestConfig
 
 .. js:autoclass:: Config.ClientConfig
+
+.. js:autoclass:: AuditLogResponse.AuditLogResponse
+
+.. js:autoclass:: AuditLogResponse.AuditLogRequest
+
+.. js:autoclass:: TypeRecommenderResponse.TypeRecommenderResponse
+
+.. js:autoclass:: TypeRecommenderResponse.ActivityRequest