emissions-api-sdk 1.0.13 → 1.0.14

package/README.md

@@ -235,6 +235,29 @@ await AuditLog.update({ logRequest: false, logResponse: false });
 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.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_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.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";
@@ -17,6 +17,9 @@ 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";

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/EconomicActivity.js

@@ -52,6 +52,51 @@ const request_1 = require("../request");
     "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

@@ -75,11 +75,8 @@ async function retrieveFactor(payload) {
  * @example
  * // Search without cross-encoder reranking
  * const searchWithoutReranker = {
-    "time":{
-      "date": "2020-06-10"
-    },
     "activity": {
-      "search" : "travel"
+      "search": "travel"
     },
     "location": {
       "country": "USA"

package/dist/api/RealEstate.js

@@ -51,7 +51,8 @@ const request_1 = require("../request");
     },
     "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/coverage/clover.xml

@@ -1,16 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<coverage generated="1782808023991" clover="3.2.0">
-  <project timestamp="1782808023991" name="All files">
-    <metrics statements="277" coveredstatements="275" conditionals="104" coveredconditionals="95" methods="36" coveredmethods="34" elements="417" coveredelements="404" complexity="0" loc="277" ncloc="277" packages="4" files="29" classes="29"/>
+<coverage generated="1790081113117" clover="3.2.0">
+  <project timestamp="1790081113117" name="All files">
+    <metrics statements="295" coveredstatements="293" conditionals="104" coveredconditionals="95" methods="39" coveredmethods="37" elements="438" coveredelements="425" complexity="0" loc="295" ncloc="295" packages="4" files="30" classes="30"/>
     <package name="src">
-      <metrics statements="104" coveredstatements="102" conditionals="70" coveredconditionals="64" methods="12" coveredmethods="10"/>
+      <metrics statements="107" coveredstatements="105" conditionals="70" coveredconditionals="64" methods="12" coveredmethods="10"/>
       <file name="Client.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/Client.ts">
         <metrics statements="63" coveredstatements="61" conditionals="68" coveredconditionals="63" methods="10" coveredmethods="8"/>
-        <line num="1" count="6" type="stmt"/>
-        <line num="3" count="6" type="stmt"/>
-        <line num="4" count="6" type="stmt"/>
-        <line num="6" count="6" type="stmt"/>
-        <line num="7" count="6" type="stmt"/>
+        <line num="1" count="7" type="stmt"/>
+        <line num="3" count="7" type="stmt"/>
+        <line num="4" count="7" type="stmt"/>
+        <line num="6" count="7" type="stmt"/>
+        <line num="7" count="7" type="stmt"/>
         <line num="25" count="50" type="cond" truecount="4" falsecount="0"/>
         <line num="26" count="50" type="stmt"/>
         <line num="27" count="50" type="stmt"/>
@@ -71,50 +71,53 @@
         <line num="314" count="8" type="stmt"/>
       </file>
       <file name="Constants.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/Constants.ts">
-        <metrics statements="27" coveredstatements="27" conditionals="0" coveredconditionals="0" methods="0" coveredmethods="0"/>
-        <line num="1" count="8" type="stmt"/>
-        <line num="2" count="8" type="stmt"/>
-        <line num="3" count="8" type="stmt"/>
-        <line num="4" count="8" type="stmt"/>
-        <line num="5" count="8" type="stmt"/>
-        <line num="6" count="8" type="stmt"/>
-        <line num="7" count="8" type="stmt"/>
-        <line num="8" count="8" type="stmt"/>
-        <line num="9" count="8" type="stmt"/>
-        <line num="10" count="8" type="stmt"/>
-        <line num="11" count="8" type="stmt"/>
-        <line num="12" count="8" type="stmt"/>
-        <line num="13" count="8" type="stmt"/>
-        <line num="14" count="8" type="stmt"/>
-        <line num="15" count="8" type="stmt"/>
-        <line num="16" count="8" type="stmt"/>
-        <line num="18" count="8" type="stmt"/>
-        <line num="20" count="8" type="stmt"/>
-        <line num="22" count="8" type="stmt"/>
-        <line num="23" count="8" type="stmt"/>
-        <line num="24" count="8" type="stmt"/>
-        <line num="26" count="8" type="stmt"/>
-        <line num="27" count="8" type="stmt"/>
-        <line num="28" count="8" type="stmt"/>
-        <line num="29" count="8" type="stmt"/>
-        <line num="30" count="8" type="stmt"/>
-        <line num="31" count="8" type="stmt"/>
+        <metrics statements="30" coveredstatements="30" conditionals="0" coveredconditionals="0" methods="0" coveredmethods="0"/>
+        <line num="1" count="11" type="stmt"/>
+        <line num="2" count="11" type="stmt"/>
+        <line num="3" count="11" type="stmt"/>
+        <line num="4" count="11" type="stmt"/>
+        <line num="5" count="11" type="stmt"/>
+        <line num="6" count="11" type="stmt"/>
+        <line num="7" count="11" type="stmt"/>
+        <line num="8" count="11" type="stmt"/>
+        <line num="9" count="11" type="stmt"/>
+        <line num="10" count="11" type="stmt"/>
+        <line num="11" count="11" type="stmt"/>
+        <line num="12" count="11" type="stmt"/>
+        <line num="13" count="11" type="stmt"/>
+        <line num="14" count="11" type="stmt"/>
+        <line num="15" count="11" type="stmt"/>
+        <line num="16" count="11" type="stmt"/>
+        <line num="17" count="11" type="stmt"/>
+        <line num="18" count="11" type="stmt"/>
+        <line num="19" count="11" type="stmt"/>
+        <line num="21" count="11" type="stmt"/>
+        <line num="23" count="11" type="stmt"/>
+        <line num="25" count="11" type="stmt"/>
+        <line num="26" count="11" type="stmt"/>
+        <line num="27" count="11" type="stmt"/>
+        <line num="29" count="11" type="stmt"/>
+        <line num="30" count="11" type="stmt"/>
+        <line num="31" count="11" type="stmt"/>
+        <line num="32" count="11" type="stmt"/>
+        <line num="33" count="11" type="stmt"/>
+        <line num="34" count="11" type="stmt"/>
       </file>
       <file name="request.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/request.ts">
         <metrics statements="9" coveredstatements="9" conditionals="0" coveredconditionals="0" methods="1" coveredmethods="1"/>
-        <line num="1" count="4" type="stmt"/>
-        <line num="3" count="4" type="stmt"/>
-        <line num="4" count="4" type="stmt"/>
-        <line num="30" count="4" type="stmt"/>
+        <line num="1" count="5" type="stmt"/>
+        <line num="3" count="5" type="stmt"/>
+        <line num="4" count="5" type="stmt"/>
+        <line num="30" count="5" type="stmt"/>
         <line num="31" count="3" type="stmt"/>
         <line num="32" count="3" type="stmt"/>
         <line num="34" count="3" type="stmt"/>
-        <line num="48" count="3" type="stmt"/>
-        <line num="49" count="2" type="stmt"/>
+        <line num="49" count="3" type="stmt"/>
+        <line num="50" count="2" type="stmt"/>
       </file>
       <file name="utils.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/utils.ts">
         <metrics statements="5" coveredstatements="5" conditionals="2" coveredconditionals="1" methods="1" coveredmethods="1"/>
-        <line num="14" count="6" type="stmt"/>
+        <line num="14" count="7" type="stmt"/>
         <line num="15" count="45" type="stmt"/>
         <line num="16" count="45" type="stmt"/>
         <line num="17" count="45" type="cond" truecount="1" falsecount="1"/>
@@ -122,7 +125,25 @@
       </file>
     </package>
     <package name="src.api">
-      <metrics statements="148" coveredstatements="148" conditionals="34" coveredconditionals="31" methods="23" coveredmethods="23"/>
+      <metrics statements="163" coveredstatements="163" conditionals="34" coveredconditionals="31" methods="26" coveredmethods="26"/>
+      <file name="AuditExport.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/api/AuditExport.ts">
+        <metrics statements="15" coveredstatements="15" conditionals="0" coveredconditionals="0" methods="3" coveredmethods="3"/>
+        <line num="2" count="1" type="stmt"/>
+        <line num="3" count="1" type="stmt"/>
+        <line num="15" count="1" type="stmt"/>
+        <line num="32" count="1" type="stmt"/>
+        <line num="35" count="1" type="stmt"/>
+        <line num="36" count="1" type="stmt"/>
+        <line num="38" count="1" type="stmt"/>
+        <line num="56" count="1" type="stmt"/>
+        <line num="59" count="1" type="stmt"/>
+        <line num="60" count="1" type="stmt"/>
+        <line num="62" count="1" type="stmt"/>
+        <line num="80" count="1" type="stmt"/>
+        <line num="81" count="1" type="stmt"/>
+        <line num="82" count="1" type="stmt"/>
+        <line num="84" count="1" type="stmt"/>
+      </file>
       <file name="AuditLog.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/api/AuditLog.ts">
         <metrics statements="26" coveredstatements="26" conditionals="21" coveredconditionals="19" methods="3" coveredmethods="3"/>
         <line num="1" count="2" type="stmt"/>
@@ -167,10 +188,10 @@
         <line num="1" count="1" type="stmt"/>
         <line num="2" count="1" type="stmt"/>
         <line num="6" count="1" type="stmt"/>
-        <line num="58" count="1" type="stmt"/>
-        <line num="61" count="2" type="stmt"/>
-        <line num="62" count="2" type="stmt"/>
-        <line num="64" count="2" type="stmt"/>
+        <line num="103" count="1" type="stmt"/>
+        <line num="106" count="2" type="stmt"/>
+        <line num="107" count="2" type="stmt"/>
+        <line num="109" count="2" type="stmt"/>
       </file>
       <file name="Factor.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/api/Factor.ts">
         <metrics statements="11" coveredstatements="11" conditionals="0" coveredconditionals="0" methods="2" coveredmethods="2"/>
@@ -181,10 +202,10 @@
         <line num="44" count="1" type="stmt"/>
         <line num="45" count="1" type="stmt"/>
         <line num="47" count="1" type="stmt"/>
+        <line num="144" count="1" type="stmt"/>
         <line num="147" count="1" type="stmt"/>
+        <line num="148" count="1" type="stmt"/>
         <line num="150" count="1" type="stmt"/>
-        <line num="151" count="1" type="stmt"/>
-        <line num="153" count="1" type="stmt"/>
       </file>
       <file name="FactorSets.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/api/FactorSets.ts">
         <metrics statements="7" coveredstatements="7" conditionals="0" coveredconditionals="0" methods="1" coveredmethods="1"/>
@@ -271,10 +292,10 @@
         <line num="1" count="1" type="stmt"/>
         <line num="2" count="1" type="stmt"/>
         <line num="6" count="1" type="stmt"/>
-        <line num="57" count="1" type="stmt"/>
-        <line num="60" count="2" type="stmt"/>
+        <line num="58" count="1" type="stmt"/>
         <line num="61" count="2" type="stmt"/>
-        <line num="63" count="2" type="stmt"/>
+        <line num="62" count="2" type="stmt"/>
+        <line num="64" count="2" type="stmt"/>
       </file>
       <file name="Stationary.ts" path="/Users/santhosh/Documents/GIT/open-source/ibm-envizi-emissions-api-nodejs-sdk/src/api/Stationary.ts">
         <metrics statements="7" coveredstatements="7" conditionals="0" coveredconditionals="0" methods="1" coveredmethods="1"/>