emissions-api-sdk 1.0.12 → 1.0.14

package/sphinx-build/source/index.rst

@@ -7,6 +7,8 @@ IBM Envizi - Emissions API Node.js SDK
 
    getting_started
    sdk
+   authentication
+   client
    reference
    troubleshooting
 
@@ -27,6 +29,17 @@ Supported Emission Types
 * **Transportation & distribution** – logistics and supply chain activities
 * **Real Estate** – emissions from commercial and residential properties
 * **Economic Activity** – spend-based emissions from business activities
+* **Physical Activity** – scope 3 emissions from physical activities with attribution for private companies (equity/debt or EVIC-based)
 * **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
+* **Audit Export API** – export, monitor, and download organization audit data

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
@@ -30,6 +32,36 @@ API
 .. js:autofunction:: RealEstate.calculate
 
 .. js:autofunction:: EconomicActivity.calculate
+   
+.. js:autofunction:: PhysicalActivity.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
+
+
+Audit Export API
+================
+
+The Audit Export API asynchronously generates an audit-data ZIP archive for an admin user. Call ``trigger`` to create an export, ``getStatus`` until it is complete, and ``download`` to retrieve the archive.
+
+.. js:autofunction:: AuditExport.trigger
+
+.. js:autofunction:: AuditExport.getStatus
+
+.. js:autofunction:: AuditExport.download
 
 
 Global Metadata API
@@ -113,3 +145,19 @@ 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
+
+.. js:autoclass:: AuditExportResponse.AuditExportRequest
+
+.. js:autoclass:: AuditExportResponse.AuditExportResponse
+
+.. js:autoclass:: AuditExportResponse.AuditExportStatusResponse
+
+.. js:autoclass:: AuditExportResponse.AuditExportLinks

package/sphinx-build/source/troubleshooting.rst

@@ -99,12 +99,61 @@ These errors occur when ``Client.getClient()`` is called with invalid or missing
 
 ----
 
+4. Missing Client ID with PAT Token
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Error Message:**
+
+.. code-block:: text
+
+   Error: If patToken is provided, "clientId" must also be provided.
+
+**Cause:** Personal Access Token (PAT) provided without client ID
+
+**Solution:** Provide ``clientId`` parameter when using a PAT token
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     patToken: 'your-pat-token'
+     // Missing clientId parameter
+   });
+
+----
+
+5. Organization ID Provided with PAT Token
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Error Message:**
+
+.. code-block:: text
+
+   Error: orgId should not be provided when using patToken.
+
+**Cause:** Organization ID should not be used with Personal Access Token authentication
+
+**Solution:** Remove ``orgId`` parameter when using PAT token authentication
+
+**Sample Function Call That Causes This Error:**
+
+.. code-block:: typescript
+
+   await Client.getClient({
+     patToken: 'your-pat-token',
+     clientId: 'client123',
+     orgId: 'org456'  // This should not be provided with PAT token
+   });
+
+----
+
 Authentication Errors (HTTP 401)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These errors occur when authentication credentials are invalid or expired.
 
-4. Invalid API Key
+6. Invalid API Key
 ^^^^^^^^^^^^^^^^^^
 
 **Error Response:**
@@ -135,7 +184,7 @@ These errors occur when authentication credentials are invalid or expired.
 
 ----
 
-5. Invalid Organization ID
+7. Invalid Organization ID
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 **Error Response:**
@@ -166,7 +215,7 @@ These errors occur when authentication credentials are invalid or expired.
 
 ----
 
-6. Invalid Client ID
+8. Invalid Client ID
 ^^^^^^^^^^^^^^^^^^^^^
 
 **Error Response:**
@@ -197,7 +246,7 @@ These errors occur when authentication credentials are invalid or expired.
 
 ----
 
-7. Empty Token Response
+9. Empty Token Response
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 **Error Message:**
@@ -233,8 +282,8 @@ These errors occur when authentication credentials are invalid or expired.
 
 ----
 
-8. Missing Expiry Field in Token
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+10. Missing Expiry Field in Token
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 **Error Message:**
 
@@ -341,6 +390,14 @@ Error Summary Table
      - ``If apiKey is provided , "clientId" and "OrgId" must also be provided.``
      - N/A
      - Provide all three parameters
+   * - Configuration
+     - ``If patToken is provided, "clientId" must also be provided.``
+     - N/A
+     - Provide clientId with PAT token
+   * - Configuration
+     - ``orgId should not be provided when using patToken.``
+     - N/A
+     - Remove orgId when using PAT token
    * - Authentication
      - ``Cannot pass the security checks...``
      - 401
@@ -369,14 +426,22 @@ Required Configuration Parameters
 
 When calling ``Client.getClient()``, the following parameters are required based on authentication method:
 
-API Key Authentication (Recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Personal Access Token (PAT) Authentication (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``patToken`` - Your Personal Access Token
+- ``clientId`` - Your client ID
+
+**Note:** Do not provide ``orgId`` when using PAT token authentication.
+
+API Key Authentication
+~~~~~~~~~~~~~~~~~~~~~~
 
 - ``apiKey`` - Your IBM Cloud API key
 - ``clientId`` - Your client ID
 - ``orgId`` - Your organization ID
-- ``host`` - API host URL
-- ``authUrl`` - Authentication URL
+- ``host`` - API host URL (optional, uses default if not provided)
+- ``authUrl`` - Authentication URL (optional, uses default if not provided)
 
 Token Authentication
 ~~~~~~~~~~~~~~~~~~~~
@@ -479,8 +544,8 @@ For issues not covered in this guide:
 
 ----
 
-**Last Updated:** 2025-11-24
+**Last Updated:** 2026-05-31
 
-**SDK Version:** 1.0.1
+**SDK Version:** 1.0.2
 
 **Coverage:** SDK initialization, client instance, and authentication errors

package/src/Constants.ts

@@ -12,6 +12,11 @@ export const FACTOR_SET_API_PATH = "/v3/carbon/factorset";
 export const SEARCH_API_PATH = "/v3/carbon/factor/search";
 export const ECONOMIC_ACTIVITY_API_PATH = "/v3/carbon/economic-activity";
 export const REAL_ESTATE_API_PATH = "/v3/carbon/real-estate";
+export const PHYSICAL_ACTIVITY_API_PATH = "/v3/carbon/physical-activity";
+export const AUDIT_LOG_API_PATH = "/v3/carbon/admin/audit-log";
+export const AUDIT_EXPORT_API_PATH = "/v3/carbon/audit";
+export const AUDIT_EXPORT_STATUS_API_PATH = "/v3/carbon/audit/status";
+export const AUDIT_EXPORT_DOWNLOAD_API_PATH = "/v3/carbon/audit/download";
 
 export const TYPE_RECOMMENDER_API_PATH = "/v3/carbon/recommender/type/search";
 
@@ -23,6 +28,7 @@ export const METADATA_UNITS_ENDPOINT = "/v3/carbon/metadata/units";
 
 export const GET = "GET";
 export const POST = "POST";
+export const PUT = "PUT";
 export const CLIENT_SOURCE_HEADER = "X-Client-Source";
 export const CLIENT_SOURCE_EXCEL = "excel";
 export const CLIENT_SOURCE_SDK = "node-sdk";

package/src/api/AuditExport.ts

@@ -0,0 +1,90 @@
+import { Buffer } from "node:buffer";
+import { Client } from "../Client";
+import {
+  AUDIT_EXPORT_API_PATH,
+  AUDIT_EXPORT_DOWNLOAD_API_PATH,
+  AUDIT_EXPORT_STATUS_API_PATH,
+  GET,
+  POST,
+} from "../Constants";
+import {
+  AuditExportRequest,
+  AuditExportResponse,
+  AuditExportStatusResponse,
+} from "../interfaces/response/AuditExportResponse";
+import { makeApiRequest } from "../request";
+
+/**
+ * Triggers an asynchronous audit data export.
+ *
+ * @export
+ * @param {AuditExportRequest} payload - Date range and optional API-name filter for the export
+ * @return {Promise<AuditExportResponse>} The accepted export request, including its request ID
+ * @throws {Error} Throws if the request is invalid, the caller is not an admin, or a matching export already exists
+ *
+ * @example
+ * const auditExport = await trigger({
+ *   fromDate: "2025-01-01",
+ *   toDate: "2025-03-31",
+ *   apiName: "location"
+ * });
+ */
+export async function trigger(
+  payload: AuditExportRequest
+): Promise<AuditExportResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + AUDIT_EXPORT_API_PATH;
+
+  return makeApiRequest<AuditExportResponse>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}
+
+/**
+ * Retrieves the processing status of an audit export.
+ *
+ * @export
+ * @param {string} requestId - Request ID returned by trigger
+ * @return {Promise<AuditExportStatusResponse>} Current export status and, when complete, download details
+ * @throws {Error} Throws if the request ID is invalid or the caller is not an admin
+ *
+ * @example
+ * const status = await getStatus(auditExport.requestId);
+ */
+export async function getStatus(
+  requestId: string
+): Promise<AuditExportStatusResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + AUDIT_EXPORT_STATUS_API_PATH;
+
+  return makeApiRequest<AuditExportStatusResponse>({
+    method: GET,
+    url,
+    params: { requestId },
+  });
+}
+
+/**
+ * Downloads a completed audit export as a ZIP archive.
+ *
+ * @export
+ * @param {string} requestId - Request ID returned by trigger
+ * @return {Promise<Buffer>} ZIP archive containing audit-export.csv
+ * @throws {Error} Throws while processing, when the export failed or expired, or if the caller is not an admin
+ *
+ * @example
+ * const auditExportZip = await download(auditExport.requestId);
+ */
+export async function download(requestId: string): Promise<Buffer> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + AUDIT_EXPORT_DOWNLOAD_API_PATH;
+
+  return makeApiRequest<Buffer>({
+    method: GET,
+    url,
+    params: { requestId },
+    responseType: "arraybuffer",
+  });
+}

package/src/api/AuditLog.ts

@@ -0,0 +1,102 @@
+import axios from "axios";
+import { makeApiRequest } from "../request";
+import { AUDIT_LOG_API_PATH, GET, PUT } from "../Constants";
+import { AuditLogRequest, AuditLogResponse } from "../interfaces/response/AuditLogResponse";
+import { Client } from "../Client";
+
+/**
+ * Handles common error responses for audit log API calls.
+ *
+ * @param {unknown} error - The error to handle
+ * @param {boolean} handle409 - Whether to handle 409 Conflict status (returns data instead of throwing)
+ * @return {AuditLogResponse | never} Returns response data for 409, otherwise throws error
+ */
+function handleAuditLogError(error: unknown, handle409: boolean = false): AuditLogResponse | never {
+  if (axios.isAxiosError(error) && error.response) {
+    const status = error.response.status;
+    const responseData = error.response.data;
+    
+    // Handle 409 Conflict - configuration is already set to the requested values
+    if (status === 409 && handle409) {
+      return responseData as AuditLogResponse;
+    }
+    
+    // Handle 400 Bad Request - invalid payload
+    if (status === 400) {
+      throw new Error(responseData?.message);
+    }
+    
+    // Handle 403 Forbidden - insufficient permissions
+    if (status === 403) {
+      throw new Error(responseData?.message);
+    }
+  }
+  
+  // Re-throw any other errors
+  throw error;
+}
+
+/**
+ * Retrieves the audit log configuration for the organization.
+ *
+ * Controls whether the organization's API requests and responses are stored for auditing.
+ * Organizations can disable this if they don't need their API calls to be audited.
+ *
+ * @export
+ * @return {Promise<AuditLogResponse>} Current audit log configuration
+ * @throws {Error} Throws error for 403 (Forbidden) or other failures
+ *
+ * @example
+ * const config = await getConfig();
+ * // Output: { logRequest: true, logResponse: false }
+ */
+export async function getAuditConfig(): Promise<AuditLogResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + AUDIT_LOG_API_PATH;
+
+  try {
+    return await makeApiRequest<AuditLogResponse>({
+      method: GET,
+      url,
+    });
+  } catch (error) {
+    return handleAuditLogError(error);
+  }
+}
+
+/**
+ * Updates the audit log configuration for the organization.
+ *
+ * Controls whether the organization's API requests and responses are stored for auditing.
+ * Organizations can disable this if they don't need their API calls to be audited.
+ *
+ * Note: If the configuration is already set to the requested values, the API will return
+ * a 409 Conflict status with a message indicating no change was made. This is handled
+ * gracefully and the current configuration is returned.
+ *
+ * @export
+ * @param {AuditLogRequest} payload - Audit log configuration
+ * @return {Promise<AuditLogResponse>} Updated configuration or current configuration if no change
+ * @throws {Error} Throws error for 400 (Bad Request), 403 (Forbidden), or other failures
+ *
+ * @example
+ * const result = await update({ logRequest: false, logResponse: false });
+ * // If already set to these values:
+ * // { logRequest: false, logResponse: false, message: "No change in audit log configuration" }
+ */
+export async function updateAuditConfig(
+  payload: AuditLogRequest
+): Promise<AuditLogResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + AUDIT_LOG_API_PATH;
+
+  try {
+    return await makeApiRequest<AuditLogResponse>({
+      method: PUT,
+      url,
+      data: payload,
+    });
+  } catch (error) {
+    return handleAuditLogError(error, true);
+  }
+}

package/src/api/EconomicActivity.ts

@@ -7,6 +7,7 @@ import { makeApiRequest } from "../request";
 
 /**
  * Performs scope 3 Spend based emission calculations by making a POST request to the economic activity API endpoint.
+ * Supports optional attribution with revenue for proportional allocation.
  *
  * @export
  * @param {CommonRequest} payload - The request data to be sent to the API
@@ -14,6 +15,7 @@ import { makeApiRequest } from "../request";
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
+ * // Basic economic activity request
  * const request = {
     "time": {
       "date": "2025-01-04"
@@ -29,6 +31,73 @@ import { makeApiRequest } from "../request";
     "includeDetails": false
   };
  * const result = await calculate(request);
+ *
+ * @example
+ * // Economic activity request with revenue attribution
+ * const requestWithAttribution = {
+    "time": {
+      "date": "2025-01-04"
+    },
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "type": "accomodation",
+      "value": 1500.12,
+      "unit": "usd"
+    },
+    "attribution": {
+      "outstandingAmount": 500000.0,
+      "revenue": 2000000.0
+    },
+    "includeDetails": true
+  };
+ * const resultWithAttribution = await calculate(requestWithAttribution);
+ *
+ * @example
+ * // Economic activity request with attribution (equity/debt based for private companies)
+ * const requestWithEquityDebt = {
+     "time": {
+       "date": "2025-01-04"
+     },
+     "location": {
+       "country": "usa"
+     },
+     "activity": {
+       "type": "accomodation",
+       "value": 1500.12,
+       "unit": "usd"
+     },
+     "attribution": {
+       "outstandingAmount": 500000.0,
+       "totalEquity": 3000000.0,
+       "totalDebt": 2000000.0
+     },
+     "includeDetails": true
+   };
+ * const resultWithEquityDebt = await calculate(requestWithEquityDebt);
+ *
+ * @example
+ * // Economic activity request with attribution (EVIC based for listed companies)
+ * const requestWithEvic = {
+     "time": {
+       "date": "2025-01-04"
+     },
+     "location": {
+       "country": "usa"
+     },
+     "activity": {
+       "type": "accomodation",
+       "value": 1500.12,
+       "unit": "usd"
+     },
+     "attribution": {
+       "outstandingAmount": 500000.0,
+       "evic": 10000000.0
+     },
+     "includeDetails": true
+   };
+ * const resultWithEvic = await calculate(requestWithEvic);
  */
 
 export async function calculate(

package/src/api/Factor.ts

@@ -60,6 +60,9 @@ export async function retrieveFactor(
  * @return {Promise<SearchResponse>} A promise that resolves to the search results returned by the API
  * @throws {Error} May throw an error if the API request fails
  *
+ * The API applies cross-encoder reranking by default. Set `enableReranker` to
+ * `false` to keep semantic similarity ordering without reranking.
+ *
  * @example
  * // Basic search
  * const searchRequest = {
@@ -76,6 +79,19 @@ export async function retrieveFactor(
  * const results = await search(searchRequest);
  *
  * @example
+ * // Search without cross-encoder reranking
+ * const searchWithoutReranker = {
+    "activity": {
+      "search": "travel"
+    },
+    "location": {
+      "country": "USA"
+    },
+    "enableReranker": false
+  };
+ * const results = await search(searchWithoutReranker);
+ *
+ * @example
  * // Search with optional unit parameter
  * const searchWithUnit = {
     "time":{
@@ -136,4 +152,4 @@ export async function search(
     url,
     data: payload,
   });
-}
+}

package/src/api/PhysicalActivity.ts

@@ -0,0 +1,92 @@
+import { Client } from "../Client";
+import { PHYSICAL_ACTIVITY_API_PATH, POST } from "../Constants";
+import { CommonRequest } from "../interfaces/Api";
+import { EmissionResponse } from "../interfaces/response/EmissionResponse";
+import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResponseWithDetails";
+import { makeApiRequest } from "../request";
+
+/**
+ * Performs scope 3 Physical activity emission calculations by making a POST request to the physical activity API endpoint.
+ * Supports attribution for private companies using equity/debt based calculations or EVIC (Enterprise Value Including Cash).
+ *
+ * @export
+ * @param {CommonRequest} payload - The request data to be sent to 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
+ * // Basic physical activity request
+ * const request = {
+    "time": {
+      "date": "2025-01-23"
+    },
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "type": "commercial real estate",
+      "value": 0.1,
+      "unit": "km2"
+    },
+    "includeDetails": true
+  };
+ * const result = await calculate(request);
+ *
+ * @example
+ * // Physical activity request with attribution (equity/debt based for private companies)
+ * const requestWithEquityDebt = {
+    "time": {
+      "date": "2025-01-23"
+    },
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "type": "commercial real estate",
+      "value": 0.1,
+      "unit": "km2"
+    },
+    "attribution": {
+      "outstandingAmount": 1000000,
+      "totalEquity": 3000000,
+      "totalDebt": 2000000
+    },
+    "includeDetails": true
+  };
+ * const resultWithEquityDebt = await calculate(requestWithEquityDebt);
+ *
+ * @example
+ * // Physical activity request with attribution (EVIC based)
+ * const requestWithEVIC = {
+    "time": {
+      "date": "2025-01-23"
+    },
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "type": "commercial real estate",
+      "value": 0.1,
+      "unit": "km2"
+    },
+    "attribution": {
+      "outstandingAmount": 1000000.0,
+      "evic": 10000000.0
+    },
+    "includeDetails": true
+  };
+ * const resultWithEVIC = await calculate(requestWithEVIC);
+ */
+
+export async function calculate(
+  payload: CommonRequest
+): Promise<EmissionResponse | EmissionResponseWithDetails> {
+  const client = Client.getInstance();
+  const url =  client.getDomain() + PHYSICAL_ACTIVITY_API_PATH;
+
+  return makeApiRequest<EmissionResponse | EmissionResponseWithDetails>({
+    method: POST,
+    url,
+    data: payload,
+  });
+}