emissions-api-sdk 1.0.11 → 1.0.13

package/README.md

@@ -69,6 +69,145 @@ const typeUnits = await Metadata.getUnits('Natural Gas'); // Units for specific
 
 **Supported endpoints**: `calculation`, `location`, `stationary`, `mobile`, `fugitive`, `factor`, `search`, `transportation-and-distribution`, `economic-activity`, `real-estate`
 
+
+## Type Recommender API
+
+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';
+
+// Basic search with natural language
+const types = await TypeRecommender.search({
+  "location": {
+    "country": "usa"
+  },
+  "activity": {
+    "search": "employee travelled by electric vehicle"
+  }
+});
+
+// Search with unit filter
+const typesWithUnit = await TypeRecommender.search({
+  "location": {
+    "country": "usa"
+  },
+  "activity": {
+    "search": "office consumed electricity",
+    "unit": "kWh"
+  }
+});
+
+// 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": {
+    "country": "usa"
+  },
+  "activity": {
+    "search": "heating with natural gas",
+    "scope": "1"
+  }
+});
+
+// Search with pagination and filters
+const typesWithAll = await TypeRecommender.search({
+  "location": {
+    "country": "usa",
+    "stateProvince": "california"
+  },
+  "time": {
+    "date": "2025-06-10"
+  },
+  "activity": {
+    "search": "purchased electricity for data center",
+    "unit": "MWh",
+    "scope": "2"
+  },
+  "pagination": {
+    "page": 1,
+    "size": 10
+  }
+});
+```
+
+## Factor Search API
+
+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';
+
+// Basic search with natural language
+const results = await Factor.search({
+  "time": {
+    "date": "2020-06-10"
+  },
+  "activity": {
+    "search": "employee business travel by air"
+  },
+  "location": {
+    "country": "USA"
+  }
+});
+
+// Search with unit filter
+const resultsWithUnit = await Factor.search({
+  "activity": {
+    "search": "office electricity consumption",
+    "unit": "kWh"
+  },
+  "location": {
+    "country": "USA"
+  }
+});
+
+// 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": {
+    "search": "facility heating with natural gas",
+    "scope": "1"
+  },
+  "location": {
+    "country": "USA"
+  }
+});
+
+// Search with both unit and scope
+const resultsWithBoth = await Factor.search({
+  "activity": {
+    "search": "purchased electricity for manufacturing",
+    "unit": "MWh",
+    "scope": "2"
+  },
+  "location": {
+    "country": "USA",
+    "stateProvince": "california"
+  }
+});
+```
+
 ### Get Organization Usage
 ```javascript
 import { Usage } from 'emissions-api-sdk';
@@ -78,6 +217,24 @@ 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 });
+```
+
 ## 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_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,8 @@ 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.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 +24,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/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,28 @@ 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);
  */
 async function calculate(payload) {
     const client = Client_1.Client.getInstance();

package/dist/api/Factor.js

@@ -54,18 +54,89 @@ 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 = {
     "time":{
       "date": "2020-06-10"
     },
     "activity": {
-      "search" : "travel"},
+      "search" : "travel"
+    },
     "location": {
       "country": "USA"
     }
   };
  * const results = await search(searchRequest);
+ *
+ * @example
+ * // Search without cross-encoder reranking
+ * const searchWithoutReranker = {
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search" : "travel"
+    },
+    "location": {
+      "country": "USA"
+    },
+    "enableReranker": false
+  };
+ * const results = await search(searchWithoutReranker);
+ *
+ * @example
+ * // Search with optional unit parameter
+ * const searchWithUnit = {
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search": "electricity",
+      "unit": "kWh"
+    },
+    "location": {
+      "country": "USA"
+    }
+  };
+ * const results = await search(searchWithUnit);
+ *
+ * @example
+ * // Search with optional scope parameter
+ * const searchWithScope = {
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search": "natural gas",
+      "scope": "1"
+    },
+    "location": {
+      "country": "USA"
+    }
+  };
+ * const results = await search(searchWithScope);
+ *
+ * @example
+ * // Search with both unit and scope parameters
+ * const searchWithBoth = {
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search": "electricity",
+      "unit": "MWh",
+      "scope": "2"
+    },
+    "location": {
+      "country": "USA",
+      "stateProvince": "california"
+    }
+  };
+ * const results = await search(searchWithBoth);
  */
 async function search(payload) {
     const client = Client_1.Client.getInstance();

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,6 +29,28 @@ 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
+  };
  */
 async function calculate(payload) {
     const client = Client_1.Client.getInstance();

package/dist/api/TypeRecommender.js

@@ -5,14 +5,20 @@ 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({
     "location": {
       "country": "usa"
@@ -23,6 +29,7 @@ const request_1 = require("../request");
   });
 
  * @example
+ * // Search with time and pagination
  * const result = await search({
     "location": {
       "country": "usa",
@@ -41,6 +48,7 @@ const request_1 = require("../request");
   });
  
  * @example
+ * // Search with power grid
  * const result = await search({
     "location": {
       "country": "usa",
@@ -50,6 +58,63 @@ const request_1 = require("../request");
       "search": "renewable energy"
     }
   });
+ *
+ * @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": {
+      "country": "usa"
+    },
+    "activity": {
+      "search": "electricity",
+      "unit": "kWh"
+    }
+  });
+ *
+ * @example
+ * // Search with optional scope parameter
+ * const result = await search({
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "search": "natural gas",
+      "scope": "1"
+    }
+  });
+ *
+ * @example
+ * // Search with both unit and scope parameters
+ * const result = await search({
+    "location": {
+      "country": "usa",
+      "stateProvince": "california"
+    },
+    "time": {
+      "date": "2025-06-10"
+    },
+    "activity": {
+      "search": "electricity",
+      "unit": "MWh",
+      "scope": "2"
+    },
+    "pagination": {
+      "page": 1,
+      "size": 10
+    }
+  });
  */
 async function search(payload) {
     const client = Client_1.Client.getInstance();