emissions-api-sdk 1.0.12 → 1.0.14

package/README.md

@@ -72,7 +72,7 @@ const typeUnits = await Metadata.getUnits('Natural Gas'); // Units for specific
 
 ## Type Recommender API
 
-Search for activity types using semantic search with optional unit and scope filtering:
+Search for activity types using semantic search with optional unit and scope filtering. Reranking is enabled by default; set `enableReranker` to `false` to use semantic similarity ordering without cross-encoder reranking. Type results can include `scope`, the distinct GHG Protocol scopes associated with each activity type.
 
 ```javascript
 import { TypeRecommender } from 'emissions-api-sdk';
@@ -98,6 +98,17 @@ const typesWithUnit = await TypeRecommender.search({
   }
 });
 
+// Search without cross-encoder reranking
+const typesWithoutReranker = await TypeRecommender.search({
+  "location": {
+    "country": "usa"
+  },
+  "activity": {
+    "search": "office consumed electricity"
+  },
+  "enableReranker": false
+});
+
 // Search with scope filter
 const typesWithScope = await TypeRecommender.search({
   "location": {
@@ -132,7 +143,7 @@ const typesWithAll = await TypeRecommender.search({
 
 ## Factor Search API
 
-Search for emission factors with optional unit and scope filtering:
+Search for emission factors with optional unit and scope filtering. Reranking is enabled by default; set `enableReranker` to `false` to use semantic similarity ordering without cross-encoder reranking.
 
 ```javascript
 import { Factor } from 'emissions-api-sdk';
@@ -161,6 +172,17 @@ const resultsWithUnit = await Factor.search({
   }
 });
 
+// Search without cross-encoder reranking
+const resultsWithoutReranker = await Factor.search({
+  "activity": {
+    "search": "employee business travel by air"
+  },
+  "location": {
+    "country": "USA"
+  },
+  "enableReranker": false
+});
+
 // Search with scope filter
 const resultsWithScope = await Factor.search({
   "activity": {
@@ -195,6 +217,47 @@ import { Usage } from 'emissions-api-sdk';
 const usage = await Usage.getUsage(true);
 ```
 
+## 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.
+
+```javascript
+import { AuditLog } from 'emissions-api-sdk';
+
+// Get current configuration
+const config = await AuditLog.getConfig();
+console.log(config); // { logRequest: true, logResponse: true }
+
+// Disable storage
+await AuditLog.update({ logRequest: false, logResponse: false });
+
+// Enable only request storage
+await AuditLog.update({ logRequest: true, logResponse: false });
+```
+
+## Audit Export API
+
+Admin users can export audit data for a date range. The export is asynchronous: submit the request, poll until it is complete, then download the ZIP archive. All three endpoints require an admin JWT token.
+
+```javascript
+import { AuditExport } from 'emissions-api-sdk';
+
+const auditExport = await AuditExport.trigger({
+  fromDate: '2025-01-01',
+  toDate: '2025-03-31',
+  apiName: 'location'
+});
+
+// Repeat this request until status is COMPLETED.
+const status = await AuditExport.getStatus(auditExport.requestId);
+
+if (status.status === 'COMPLETED') {
+  const auditExportZip = await AuditExport.download(auditExport.requestId);
+}
+```
+
+The request dates use `yyyy-MM-dd`. `fromDate` must be on or after `2025-01-01`, `toDate` must be no later than the previous calendar day, and `apiName` is an optional case-insensitive endpoint filter. A completed export is available for seven days. See the [Audit Export API reference](https://ibm.github.io/ibm-envizi-emissions-api-nodejs-sdk/reference.html#audit-export-api) for the request and response details.
+
 ## Authentication
 
 The SDK supports three authentication methods:

package/dist/Constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLIENT_SOURCE_SDK = exports.CLIENT_SOURCE_EXCEL = exports.CLIENT_SOURCE_HEADER = exports.POST = exports.GET = exports.METADATA_UNITS_ENDPOINT = exports.METADATA_AREA_ENDPOINT = exports.METADATA_TYPES_ENDPOINT = exports.USAGE_API = exports.TYPE_RECOMMENDER_API_PATH = exports.REAL_ESTATE_API_PATH = exports.ECONOMIC_ACTIVITY_API_PATH = exports.SEARCH_API_PATH = exports.FACTOR_SET_API_PATH = exports.FACTOR_API_PATH = exports.TRANSPORTATION_AND_DISTRIBUTION_API_PATH = exports.GENERIC_CALCULATION_API_PATH = exports.STATIONARY_API_PATH = exports.FUGITIVE_API_PATH = exports.LOCATION_API_PATH = exports.MOBILE_API_PATH = exports.PAT_TOKEN_EXCHANGE_API = exports.TOKEN_GENERATION_API = exports.API_DOMAIN = void 0;
+exports.CLIENT_SOURCE_SDK = exports.CLIENT_SOURCE_EXCEL = exports.CLIENT_SOURCE_HEADER = exports.PUT = exports.POST = exports.GET = exports.METADATA_UNITS_ENDPOINT = exports.METADATA_AREA_ENDPOINT = exports.METADATA_TYPES_ENDPOINT = exports.USAGE_API = exports.TYPE_RECOMMENDER_API_PATH = exports.AUDIT_EXPORT_DOWNLOAD_API_PATH = exports.AUDIT_EXPORT_STATUS_API_PATH = exports.AUDIT_EXPORT_API_PATH = exports.AUDIT_LOG_API_PATH = exports.PHYSICAL_ACTIVITY_API_PATH = exports.REAL_ESTATE_API_PATH = exports.ECONOMIC_ACTIVITY_API_PATH = exports.SEARCH_API_PATH = exports.FACTOR_SET_API_PATH = exports.FACTOR_API_PATH = exports.TRANSPORTATION_AND_DISTRIBUTION_API_PATH = exports.GENERIC_CALCULATION_API_PATH = exports.STATIONARY_API_PATH = exports.FUGITIVE_API_PATH = exports.LOCATION_API_PATH = exports.MOBILE_API_PATH = exports.PAT_TOKEN_EXCHANGE_API = exports.TOKEN_GENERATION_API = exports.API_DOMAIN = void 0;
 exports.API_DOMAIN = "https://api.envizi.ibm.com/ghgemissions/run";
 exports.TOKEN_GENERATION_API = "https://api.ibm.com/saascore/run/authentication-retrieve/api-key";
 exports.PAT_TOKEN_EXCHANGE_API = "https://api.ibm.com/saascore/run/envizi-auth/exchange";
@@ -15,6 +15,11 @@ exports.FACTOR_SET_API_PATH = "/v3/carbon/factorset";
 exports.SEARCH_API_PATH = "/v3/carbon/factor/search";
 exports.ECONOMIC_ACTIVITY_API_PATH = "/v3/carbon/economic-activity";
 exports.REAL_ESTATE_API_PATH = "/v3/carbon/real-estate";
+exports.PHYSICAL_ACTIVITY_API_PATH = "/v3/carbon/physical-activity";
+exports.AUDIT_LOG_API_PATH = "/v3/carbon/admin/audit-log";
+exports.AUDIT_EXPORT_API_PATH = "/v3/carbon/audit";
+exports.AUDIT_EXPORT_STATUS_API_PATH = "/v3/carbon/audit/status";
+exports.AUDIT_EXPORT_DOWNLOAD_API_PATH = "/v3/carbon/audit/download";
 exports.TYPE_RECOMMENDER_API_PATH = "/v3/carbon/recommender/type/search";
 exports.USAGE_API = "/v3/carbon/usage";
 exports.METADATA_TYPES_ENDPOINT = "/v3/carbon/metadata/types";
@@ -22,6 +27,7 @@ exports.METADATA_AREA_ENDPOINT = "/v3/carbon/metadata/area";
 exports.METADATA_UNITS_ENDPOINT = "/v3/carbon/metadata/units";
 exports.GET = "GET";
 exports.POST = "POST";
+exports.PUT = "PUT";
 exports.CLIENT_SOURCE_HEADER = "X-Client-Source";
 exports.CLIENT_SOURCE_EXCEL = "excel";
 exports.CLIENT_SOURCE_SDK = "node-sdk";

package/dist/api/AuditExport.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trigger = trigger;
+exports.getStatus = getStatus;
+exports.download = download;
+const Client_1 = require("../Client");
+const Constants_1 = require("../Constants");
+const request_1 = require("../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"
+ * });
+ */
+async function trigger(payload) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.AUDIT_EXPORT_API_PATH;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.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);
+ */
+async function getStatus(requestId) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.AUDIT_EXPORT_STATUS_API_PATH;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.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);
+ */
+async function download(requestId) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.AUDIT_EXPORT_DOWNLOAD_API_PATH;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.GET,
+        url,
+        params: { requestId },
+        responseType: "arraybuffer",
+    });
+}

package/dist/api/AuditLog.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAuditConfig = getAuditConfig;
+exports.updateAuditConfig = updateAuditConfig;
+const axios_1 = __importDefault(require("axios"));
+const request_1 = require("../request");
+const Constants_1 = require("../Constants");
+const Client_1 = require("../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, handle409 = false) {
+    if (axios_1.default.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;
+        }
+        // Handle 400 Bad Request - invalid payload
+        if (status === 400) {
+            throw new Error(responseData === null || responseData === void 0 ? void 0 : responseData.message);
+        }
+        // Handle 403 Forbidden - insufficient permissions
+        if (status === 403) {
+            throw new Error(responseData === null || responseData === void 0 ? void 0 : 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 }
+ */
+async function getAuditConfig() {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.AUDIT_LOG_API_PATH;
+    try {
+        return await (0, request_1.makeApiRequest)({
+            method: Constants_1.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" }
+ */
+async function updateAuditConfig(payload) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.AUDIT_LOG_API_PATH;
+    try {
+        return await (0, request_1.makeApiRequest)({
+            method: Constants_1.PUT,
+            url,
+            data: payload,
+        });
+    }
+    catch (error) {
+        return handleAuditLogError(error, true);
+    }
+}

package/dist/api/EconomicActivity.js

@@ -6,6 +6,7 @@ const Constants_1 = require("../Constants");
 const request_1 = require("../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
@@ -13,6 +14,7 @@ const request_1 = require("../request");
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
+ * // Basic economic activity request
  * const request = {
     "time": {
       "date": "2025-01-04"
@@ -28,6 +30,73 @@ const request_1 = require("../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);
  */
 async function calculate(payload) {
     const client = Client_1.Client.getInstance();

package/dist/api/Factor.js

@@ -54,6 +54,9 @@ async function retrieveFactor(payload) {
  * @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 = {
@@ -70,6 +73,19 @@ async function retrieveFactor(payload) {
  * 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":{

package/dist/api/PhysicalActivity.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculate = calculate;
+const Client_1 = require("../Client");
+const Constants_1 = require("../Constants");
+const request_1 = require("../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);
+ */
+async function calculate(payload) {
+    const client = Client_1.Client.getInstance();
+    const url = client.getDomain() + Constants_1.PHYSICAL_ACTIVITY_API_PATH;
+    return (0, request_1.makeApiRequest)({
+        method: Constants_1.POST,
+        url,
+        data: payload,
+    });
+}

package/dist/api/RealEstate.js

@@ -13,6 +13,7 @@ const request_1 = require("../request");
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
+ * // Basic request without attribution
  * const request = {
     "time": {
       "date": "2025-01-04"
@@ -28,7 +29,30 @@ const request_1 = require("../request");
     "includeDetails": false
   };
  * const result = await calculate(request);
- */
+ *
+ * @example
+ * // Request with attribution (property value based)
+ * const requestWithAttribution = {
+    "time": {
+      "date": "2022-01-01"
+    },
+    "location": {
+      "country": "usa",
+      "stateProvince": "new york"
+    },
+    "activity": {
+      "type": "Commercial Real Estate:Office",
+      "value": 123456.0,
+      "unit": "m2"
+    },
+    "attribution": {
+      "outstandingAmount": 1000000.0,
+      "propertyValue": 5000000.0
+    },
+    "includeDetails": true
+  };
+* const resultWithAttribution = await calculate(requestWithAttribution);
+*/
 async function calculate(payload) {
     const client = Client_1.Client.getInstance();
     const url = client.getDomain() + Constants_1.REAL_ESTATE_API_PATH;

package/dist/api/TypeRecommender.js

@@ -5,13 +5,18 @@ const Client_1 = require("../Client");
 const Constants_1 = require("../Constants");
 const request_1 = require("../request");
 /**
- * Search for activity types using semantic search with location, time, and license context. Supports pagination.
+ * Search for activity types using semantic search with location, time, and license context. Supports pagination and optional reranker control.
  *
  * @export
  * @param {SearchRequest} payload - The search request data to be sent to the API
- * @return {Promise<TypeResponse>} A promise that resolves to the activity types returned by the API
+ * @return {Promise<TypeRecommenderResponse>} A promise that resolves to the activity types 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. Returned
+ * activity type items can include `scope`, a list of distinct GHG Protocol
+ * scopes associated with the activity type.
+ *
  * @example
  * // Basic search
  * const result = await search({
@@ -55,6 +60,18 @@ const request_1 = require("../request");
   });
  *
  * @example
+ * // Search without cross-encoder reranking
+ * const result = await search({
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "search": "electricity"
+    },
+    "enableReranker": false
+  });
+ *
+ * @example
  * // Search with optional unit parameter
  * const result = await search({
     "location": {