emissions-api-sdk 1.0.0 → 1.0.2

package/dist/types/interfaces/response/AreaResponse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Interface representing a location with geographical and power grid information
+ */
+export interface Location {
+    /** ISO 3166-1 alpha-3 country code */
+    alpha3: string;
+    /** Full country name */
+    countryName: string;
+    /** List of state or province names (optional) */
+    stateProvinces?: string[];
+    /** List of power grid identifiers (optional) */
+    powerGrids?: string[];
+}
+/**
+ * Interface representing the response from the area/location API
+ */
+export interface AreaResponse {
+    /** Array of location objects */
+    locations: Location[];
+}

package/dist/types/interfaces/response/EmissionResponse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Interface representing the emission calculation response
+ */
+export interface EmissionResponse {
+    /** Unique transaction identifier (required) */
+    transactionId: string;
+    /** Total CO2 equivalent emissions (required) */
+    totalCO2e: number;
+    /** CO2 emissions value (optional) */
+    CO2?: number;
+    /** CH4 (Methane) emissions value (optional) */
+    CH4?: number;
+    /** N2O (Nitrous Oxide) emissions value (optional) */
+    N2O?: number;
+    /** Biogenic CO2 emissions value (optional) */
+    bioCO2?: number;
+    /** Indirect CO2 equivalent emissions value (optional) */
+    indirectCO2e?: number;
+    /** Hydrofluorocarbon emissions value (optional) */
+    HFC?: number;
+    /** Perfluorocarbon emissions value (optional) */
+    PFC?: number;
+    /** Sulfur hexafluoride emissions value (optional) */
+    SF6?: number;
+    /** Nitrogen trifluoride emissions value (optional) */
+    NF3?: number;
+    /** Unit of measurement for emissions (required) */
+    unit: string;
+    /** Description of the emission calculation (required) */
+    description: string;
+}

package/dist/types/interfaces/response/EmissionResponseWithDetails.d.ts

@@ -0,0 +1,144 @@
+import { EmissionResponse } from './EmissionResponse';
+/**
+ * Interface for unit information in emission details
+ */
+export interface UnitInfo {
+    /** Unit name */
+    name: string;
+    /** Unit description (optional) */
+    description?: string;
+}
+/**
+ * Interface for area information
+ */
+export interface AreaInfo {
+    /** Internal name of the area */
+    internalName: string;
+    /** Standard name of the area */
+    standardName: string;
+    alpha3?: string;
+}
+/**
+ * Interface for area type information
+ */
+export interface AreaType {
+    /** Type name (e.g., "Planet", "State") */
+    name: string;
+}
+/**
+ * Interface for factor data type categories
+ */
+export interface FactorDataTypeCategory {
+    /** Category name */
+    name: string;
+}
+/**
+ * Interface for factor set information
+ */
+export interface FactorSetInfo {
+    /** Factor set type */
+    type: string;
+    /** Description of the factor set */
+    description?: string;
+    /** Provider of the factor set */
+    provider?: string;
+    /** Source URL for the factor set */
+    sourceUrl?: string;
+    factorSource?: string;
+}
+export interface FactorSelectionDefault {
+    actorDataType?: string;
+    areaName?: string;
+    factorSetName?: string;
+}
+/**
+ * Interface for factor data type code
+ */
+export interface FactorDataTypeCode {
+    /** Unit of measure */
+    unitOfMeasure: string;
+    /** Activity type */
+    type: string;
+    /** Activity subtype */
+    subtype: string;
+    /** Unique factor identifier */
+    factorId: number;
+}
+/**
+ * Interface for factor set version information
+ */
+export interface FactorSetVersion {
+    /** Publication start date */
+    publishedFrom?: string;
+    /** Publication end date (optional) */
+    publishedTo?: string;
+    /** Source of the factor */
+    factorSource: string;
+}
+/**
+ * Interface for factor value
+ */
+export interface FactorValue {
+    /** Unit information */
+    unit: {
+        /** Unit name */
+        name: string;
+    };
+    /** Factor value */
+    value: number;
+}
+/**
+ * Interface for factor metadata
+ */
+export interface FactorMetaData {
+    /** Metadata key */
+    key: string;
+    /** Metadata value */
+    value: string;
+}
+/**
+ * Interface for unit conversion information
+ */
+export interface UnitConversion {
+    /** Input unit */
+    inputUnit: string;
+    /** Unit from database */
+    unitFromDb: string;
+    /** Conversion ratio */
+    conversionRatio: string;
+}
+/**
+ * Interface for detailed emission data
+ */
+export interface EmissionData {
+    /** Array of unit information */
+    unit: UnitInfo[];
+    /** Array of area information */
+    area: AreaInfo[];
+    /** Array of area types */
+    areaType: AreaType[];
+    /** Array of factor data type categories */
+    factorDataTypeCategories: FactorDataTypeCategory[];
+    factorSelectionDefault?: FactorSelectionDefault[];
+    /** Array of factor set information */
+    factorSet: FactorSetInfo[];
+    /** Array of factor data type codes */
+    factorDataTypeCode: FactorDataTypeCode[];
+    /** Array of factor set versions */
+    factorSetVersion: FactorSetVersion[];
+    /** Array of factor values */
+    factorValue: FactorValue[];
+    /** Array of factor metadata */
+    factorMetaData: FactorMetaData[];
+    /** Array of unit conversions */
+    unitConversion: UnitConversion[];
+}
+/**
+ * Interface representing the emission calculation response with detailed information
+ */
+export interface EmissionResponseWithDetails {
+    /** Emission calculation result */
+    result: EmissionResponse;
+    /** Detailed emission data */
+    data: EmissionData;
+}

package/dist/types/interfaces/response/FactorResponse.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Interface representing the response from the retrieve factor API
+ */
+export interface FactorResponse {
+    /** Unique transaction identifier */
+    transactionId: string;
+    /** Total CO2 equivalent emissions (optional - not present in all responses)*/
+    totalCO2e?: number;
+    /** CO2 emissions value (optional - not present in all responses) */
+    CO2?: number;
+    /** CH4 (Methane) emissions value (optional - not present in all responses) */
+    CH4?: number;
+    /** N2O (Nitrous Oxide) emissions value (optional - not present in all responses) */
+    N2O?: number;
+    /** Biogenic CO2 emissions value (optional - not present in all responses) */
+    bioCO2?: number;
+    /** Indirect CO2 equivalent emissions value (optional - not present in all responses) */
+    indirectCO2e?: number;
+    /** Hydrofluorocarbon emissions value (optional - not present in all responses) */
+    HFC?: number;
+    /** Perfluorocarbon emissions value (optional - not present in all responses) */
+    PFC?: number;
+    /** Sulfur hexafluoride emissions value (optional - not present in all responses) */
+    SF6?: number;
+    /** Nitrogen trifluoride emissions value (optional - not present in all responses) */
+    NF3?: number;
+    /** Unit of measurement for emissions */
+    unit?: string;
+    /** Description of the emission factors (optional)*/
+    description?: string;
+    /** Factor set identifier (e.g., "IPCC", "IGES") */
+    factorSet: string;
+    /** Source reference for the emission factors (optional)*/
+    source?: string;
+    /** Type of activity (e.g., "Gas/Diesel Oil", "Electricity") */
+    activityType: string;
+    /** Array of supported activity units */
+    activityUnit: string[];
+    /** Name of the emission factor */
+    name?: string;
+    /** Publication start date in ISO format (optional)*/
+    publishedFrom?: string;
+    /** Publication end date in ISO format (optional) */
+    publishedTo?: string;
+    /** Effective start date in ISO format (optional) */
+    effectiveFrom?: string;
+    /** Effective end date in ISO format (optional) */
+    effectiveTo?: string;
+    /** Geographic region (e.g., "Earth", "India") */
+    region: string;
+    /** Unique factor identifier */
+    factorId: number;
+}

package/dist/types/interfaces/response/FactorSetResponse.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Interface for individual factor set within the response
+ */
+export interface FactorSet {
+    /** Unique identifier for the factor set (required) */
+    id: number;
+    /** Name of the factor set (required) */
+    name: string;
+    /** License type for the factor set (required, e.g., "Public") */
+    license: string;
+    /** Number of factors in this set (required) */
+    factorCount: number;
+    /** Source URL for the factor set data */
+    sourceUrl?: string;
+    /** Detailed description of the factor set */
+    description?: string;
+    /** Short description of the factor set */
+    descriptionShort?: string;
+    /** Array of emission factor types included in this set */
+    types?: string[];
+    /** Array of regions/countries covered by this factor set */
+    regions?: string[];
+    /** Array of version years available for this factor set */
+    versions?: string[];
+    /** Provider/publisher of the factor set */
+    provider?: string;
+    /** Optional citation information for the factor set */
+    citation?: string;
+}
+/**
+ * Interface for Factor Set API response
+ */
+export interface FactorSetResponse {
+    /** Transaction ID for the API request */
+    transactionId: string;
+    /** Array of factor sets returned in the response */
+    factorSets: FactorSet[];
+}

package/dist/types/interfaces/response/SearchResponse.d.ts

@@ -0,0 +1,41 @@
+import { FactorResponse } from './FactorResponse';
+/**
+ * Pagination parameters for search requests
+ */
+export interface Pagination {
+    /** Page number */
+    page: number;
+    /** Page size */
+    size: number;
+}
+/**
+ * Request body structure for pagination links
+ */
+export interface PaginationBody {
+    /** Pagination parameters */
+    pagination?: Pagination;
+}
+/**
+ * Link object for pagination in search results
+ */
+export interface SearchLink {
+    /** Relationship type (e.g., "next", "prev") */
+    rel: string;
+    /** URL for the link */
+    href: string;
+    /** Content type */
+    type: string;
+    /** HTTP method */
+    method: string;
+    /** Request body for pagination */
+    body?: PaginationBody;
+}
+/**
+ * Interface representing the response from the search factor API
+ */
+export interface SearchResponse {
+    /** Array of factor results */
+    factors: FactorResponse[];
+    /** Pagination links (optional) */
+    links?: SearchLink[];
+}

package/dist/types/interfaces/response/TypeResponse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Interface for type metadata API
+ */
+export interface TypeResponse {
+    /** Array of string*/
+    types: string[];
+}

package/dist/types/interfaces/response/UnitResponse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Interface for /units metadata API
+ */
+export interface UnitResponse {
+    /** Array of string*/
+    units: 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.