emissions-api-sdk 1.0.11 → 1.0.13

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,8 @@ 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 TYPE_RECOMMENDER_API_PATH = "/v3/carbon/recommender/type/search";
 
@@ -23,6 +25,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/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,28 @@ 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);
  */
 
 export async function calculate(

package/src/api/Factor.ts

@@ -60,18 +60,89 @@ 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 = {
     "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);
  */
 export async function search(
   payload: SearchRequest

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,
+  });
+}

package/src/api/RealEstate.ts

@@ -14,6 +14,7 @@ import { makeApiRequest } from "../request";
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
+ * // Basic request without attribution
  * const request = {
     "time": {
       "date": "2025-01-04"
@@ -29,6 +30,28 @@ import { makeApiRequest } from "../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
+  };
  */
 
 export async function calculate(

package/src/api/TypeRecommender.ts

@@ -5,14 +5,20 @@ import { TypeRecommenderResponse } from "../interfaces/response/TypeRecommenderR
 import { makeApiRequest } from "../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 @@ import { makeApiRequest } from "../request";
   });
 
  * @example
+ * // Search with time and pagination
  * const result = await search({
     "location": {
       "country": "usa",
@@ -41,6 +48,7 @@ import { makeApiRequest } from "../request";
   });
  
  * @example
+ * // Search with power grid
  * const result = await search({
     "location": {
       "country": "usa",
@@ -50,6 +58,63 @@ import { makeApiRequest } from "../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
+    }
+  });
  */
 export async function search(
   payload: SearchRequest

package/src/index.ts

@@ -10,10 +10,15 @@ export * as Factor from './api/Factor';
 export * as FactorSets from './api/FactorSets'
 export * as EconomicActivity from './api/EconomicActivity';
 export * as RealEstate from './api/RealEstate';
+export * as PhysicalActivity from './api/PhysicalActivity';
 export * as Metadata from './api/Metadata';
 export * as TypeRecommender from './api/TypeRecommender';
+export * as AuditLog from './api/AuditLog';
 export { ClientConfig } from './interfaces/Config';
 
+// Common interfaces
+export { Attribution } from './interfaces/common';
+
 // Response interfaces
 export { AreaResponse, Location as LocationInfo } from './interfaces/response/AreaResponse';
 export { EmissionResponse } from './interfaces/response/EmissionResponse';
@@ -37,4 +42,5 @@ export {
 export { TypeResponse } from './interfaces/response/TypeResponse';
 export { UnitResponse } from './interfaces/response/UnitResponse';
 export { UsageResponse } from './interfaces/response/UsageResponse';
-export { TypeRecommenderResponse, ActivityRequest } from './interfaces/response/TypeRecommenderResponse';
+export { TypeRecommenderResponse, ActivityRequest } from './interfaces/response/TypeRecommenderResponse';
+export { AuditLogResponse, AuditLogRequest } from './interfaces/response/AuditLogResponse';