emissions-api-sdk 1.0.11 → 1.0.13

package/src/interfaces/Api.ts

@@ -1,4 +1,4 @@
-import { Activity, Location , Time, CombinedUnitsActivity, FactorActivity, SearchActivity, Pagination, FactorActivityWithFactorId, CombinedUnitsActivityWithFactorId, ActivityWithFactorId } from "./common";
+import { Activity, Location , Time, CombinedUnitsActivity, FactorActivity, SearchActivity, Pagination, FactorActivityWithFactorId, CombinedUnitsActivityWithFactorId, ActivityWithFactorId, Attribution } from "./common";
 
 /**
  * Represents activity data associated with a location, with simplified requirements.
@@ -105,7 +105,7 @@ export interface LocationRequestWithFactorId {
 /**
  * Common request parameters for calculations without specifying a factor ID.
  * Used for general-purpose calculations based on location, time, and activity data.
- * 
+ *
  * @interface CommonRequestWithoutFactorId
  */
 export interface CommonRequestWithoutFactorId {
@@ -124,18 +124,23 @@ export interface CommonRequestWithoutFactorId {
      * Contains complete activity information including type, value, and unit.
      */
     activity: Activity;
+    /**
+     * Optional attribution information for FE calculations.
+     * Contains outstanding amount, property value, and currency.
+     */
+    attribution?: Attribution;
     /**
      * Whether to include additional details in the response.
      * When true, the API will return more comprehensive information.
      * @default false
      */
     includeDetails?: boolean;
-} 
+}
 
 /**
  * Common request parameters for calculations with a specific factor ID.
  * Used when the emission factor is already known and doesn't need to be determined by location.
- * 
+ *
  * @interface CommonRequestWithFactorId
  */
 export interface CommonRequestWithFactorId {
@@ -143,13 +148,18 @@ export interface CommonRequestWithFactorId {
      * The activity data for the calculation, including the specific factor ID to use.
      */
     activity: ActivityWithFactorId;
+    /**
+     * Optional attribution information for FE calculations.
+     * Contains outstanding amount, property value, and currency.
+     */
+    attribution?: Attribution;
     /**
      * Whether to include additional details in the response.
      * When true, the API will return more comprehensive information.
      * @default false
      */
     includeDetails?: boolean;
-} 
+}
 
 /**
  * Request parameters for generic calculations without specifying a factor ID.
@@ -264,7 +274,13 @@ export interface SearchRequest {
      * Optional pagination parameters for the search results.
      * Used to limit the number of results and implement paging.
      */
-    pagination?: Pagination
+    pagination?: Pagination;
+    /**
+     * Optional reranker toggle for factor and type searches.
+     * Defaults to true when omitted. Set to false to use semantic similarity
+     * results directly without cross-encoder reranking.
+     */
+    enableReranker?: boolean;
 } 
 
 /**

package/src/interfaces/common.ts

@@ -155,6 +155,18 @@ export interface SearchActivity {
    * The search query string.
    */
   search: string;
+
+  /**
+   * Optional unit (symbol) for search activity.
+   */
+  unit?: string;
+
+  /**
+   * Optional scope(1,2,3,3.1 to 3.15) for search activity.
+   */
+
+  scope?: string;
+   
 }
 
 /**
@@ -172,3 +184,49 @@ export interface Pagination {
    */
   size: number
 }
+
+/**
+ * Represents attribution information for real estate, physical activity, and economic activity calculations.
+ * Supports four scenarios:
+ * 1. Property value based (for general real estate)
+ * 2. Equity/Debt based (for private companies)
+ * 3. EVIC based (Enterprise Value Including Cash for physical activity)
+ * 4. Revenue based (for economic activity)
+ * @interface Attribution
+ */
+export interface Attribution {
+  /**
+   * The outstanding amount for the property or activity.
+   */
+  outstandingAmount?: number;
+  
+  /**
+   * The total property value (used in property value based scenario).
+   * Optional - use either propertyValue OR (totalEquity + totalDebt) OR evic OR revenue.
+   */
+  propertyValue?: number;
+  
+  /**
+   * The total equity amount (used in equity/debt based scenario for private companies).
+   * Optional - use either propertyValue OR (totalEquity + totalDebt) OR evic OR revenue.
+   */
+  totalEquity?: number;
+  
+  /**
+   * The total debt amount (used in equity/debt based scenario for private companies).
+   * Optional - use either propertyValue OR (totalEquity + totalDebt) OR evic OR revenue.
+   */
+  totalDebt?: number;
+
+  /**
+   * Enterprise Value Including Cash (EVIC) - used in EVIC based scenario for physical activity calculations.
+   * Optional - use either propertyValue OR (totalEquity + totalDebt) OR evic OR revenue.
+   */
+  evic?: number;
+
+  /**
+   * Total revenue - used in revenue based scenario for economic activity calculations.
+   * Optional - use either propertyValue OR (totalEquity + totalDebt) OR evic OR revenue.
+   */
+  revenue?: number;
+}

package/src/interfaces/response/AuditLogResponse.ts

@@ -0,0 +1,47 @@
+/**
+ * Response interface for audit log configuration.
+ * Contains settings for logging requests and responses.
+ *
+ * @interface AuditLogResponse
+ */
+export interface AuditLogResponse {
+
+  /**
+   * Whether to log API requests.
+   * When true, all incoming requests will be logged.
+   */
+  logRequest: boolean;
+  
+  /**
+   * Whether to log API responses.
+   * When true, all outgoing responses will be logged.
+   */
+  logResponse: boolean;
+
+  /**
+   * Message providing additional context about the response.
+   */
+  message: string;
+}
+
+/**
+ * Request interface for updating audit log configuration.
+ * Used to configure which parts of API interactions should be logged.
+ * 
+ * @interface AuditLogRequest
+ */
+export interface AuditLogRequest {
+
+  /**
+   * Whether to log API requests.
+   * When true, all incoming requests will be logged.
+   */
+  logRequest: boolean;
+  
+  /**
+   * Whether to log API responses.
+   * When true, all outgoing responses will be logged.
+   */
+  logResponse: boolean;
+
+}

package/src/interfaces/response/TypeRecommenderResponse.ts

@@ -15,4 +15,6 @@ export interface ActivityRequest {
     activityDescription: string;
 
     confidence: number;
+
+    scope?: string[];
 }

package/test/apiTest.test.ts

@@ -7,10 +7,12 @@ import * as GenericCalculation from "../src/api/Calculation";
 import * as TransportationDistributionApi from "../src/api/TransportationAndDistribution";
 import * as economicActivityApi from "../src/api/EconomicActivity";
 import * as realEstateApi from "../src/api/RealEstate";
+import * as physicalActivityApi from "../src/api/PhysicalActivity";
 import * as UsageApi from "../src/api/Usage";
 import * as Factors from "../src/api/Factor";
 import * as FactorSets from "../src/api/FactorSets";
 import * as VectorTypeSearch from "../src/api/TypeRecommender";
+import * as AuditLogApi from "../src/api/AuditLog";
 
 import {
   LOCATION_API_PATH,
@@ -25,7 +27,9 @@ import {
   USAGE_API,
   ECONOMIC_ACTIVITY_API_PATH,
   REAL_ESTATE_API_PATH,
+  PHYSICAL_ACTIVITY_API_PATH,
   TYPE_RECOMMENDER_API_PATH,
+  AUDIT_LOG_API_PATH,
 } from "../src/Constants";
 import locationPayload from "./mocks/LocationRequest";
 import commonpayload from "./mocks/CommonRequest";
@@ -33,6 +37,10 @@ import { Client } from "../src/Client";
 import GenericCalculationPayload from "./mocks/GenericCalculationRequest";
 import FactorPayload from "./mocks/FactorRequest";
 import SearchPayload from "./mocks/SearchRequest";
+import physicalActivityPayload from "./mocks/PhysicalActivityRequest";
+import physicalActivityEVICPayload from "./mocks/PhysicalActivityEVICRequest";
+import economicActivityAttributionPayload from "./mocks/EconomicActivityAttributionRequest";
+import attributionPayload from "./mocks/AttributionRequest";
 
 type ApiTestCase = {
   name: string;
@@ -41,7 +49,7 @@ type ApiTestCase = {
   payload?: any;
   pathParams?: string | string[];
   queryParams?: Record<string, string> | Record<string, boolean>;
-  method: "GET" | "POST";
+  method: "GET" | "POST" | "PUT";
 };
 
 const mockResp = "mock-success-response";
@@ -103,6 +111,13 @@ const testCases: ApiTestCase[] = [
     payload: commonpayload,
     method: "POST",
   },
+  {
+    name: "Economic activity API with revenue attribution",
+    func: economicActivityApi.calculate,
+    path: ECONOMIC_ACTIVITY_API_PATH,
+    payload: economicActivityAttributionPayload,
+    method: "POST",
+  },
   {
     name: "Real estate API",
     func: realEstateApi.calculate,
@@ -110,6 +125,34 @@ const testCases: ApiTestCase[] = [
     payload: commonpayload,
     method: "POST",
   },
+  {
+    name: "Real estate API with attribution",
+    func: realEstateApi.calculate,
+    path: REAL_ESTATE_API_PATH,
+    payload: attributionPayload,
+    method: "POST",
+  },
+  {
+    name: "Physical activity API",
+    func: physicalActivityApi.calculate,
+    path: PHYSICAL_ACTIVITY_API_PATH,
+    payload: commonpayload,
+    method: "POST",
+  },
+  {
+    name: "Physical activity API with equity/debt attribution",
+    func: physicalActivityApi.calculate,
+    path: PHYSICAL_ACTIVITY_API_PATH,
+    payload: physicalActivityPayload,
+    method: "POST",
+  },
+  {
+    name: "Physical activity API with EVIC attribution",
+    func: physicalActivityApi.calculate,
+    path: PHYSICAL_ACTIVITY_API_PATH,
+    payload: physicalActivityEVICPayload,
+    method: "POST",
+  },
   {
     name: "FactorSet API",
     func: FactorSets.get,
@@ -150,6 +193,19 @@ const testCases: ApiTestCase[] = [
     path: TYPE_RECOMMENDER_API_PATH,
     payload: SearchPayload,
     method: "POST",
+  },
+  {
+    name: "AuditLog API - getAuditLogConfig",
+    func: AuditLogApi.getAuditConfig,
+    path: AUDIT_LOG_API_PATH,
+    method: "GET",
+  },
+  {
+    name: "AuditLog API - updateAuditLogConfig",
+    func: AuditLogApi.updateAuditConfig,
+    path: AUDIT_LOG_API_PATH,
+    payload: { logRequest: true, logResponse: false },
+    method: "PUT",
   }
 ];
 
@@ -186,7 +242,7 @@ describe("API Test calculate functions", () => {
     ({ func, path, payload, pathParams, queryParams, method }) => {
       it("Should call makeApiRequest with API url", async () => {
         let result;
-        if (method === "POST") {
+        if (method === "POST" || method === "PUT") {
           result = await func(payload);
         } else {
           // For GET requests with queryParams
@@ -222,7 +278,7 @@ describe("API Test calculate functions", () => {
           method,
           url: expectedUrl,
         };
-        if (method === "POST") expectedRequest.data = payload;
+        if (method === "POST" || method === "PUT") expectedRequest.data = payload;
         if (method === "GET" && queryParams) expectedRequest.params = queryParams;
         expect(spy).toHaveBeenCalledWith(expectedRequest);
         expect(result).toBe(mockResp);

package/test/auditLog.test.ts

@@ -0,0 +1,216 @@
+import axios from 'axios';
+import { getAuditConfig, updateAuditConfig } from '../src/api/AuditLog';
+import { Client } from '../src/Client';
+import * as request from '../src/request';
+
+jest.mock('../src/request');
+jest.mock('../src/Client');
+
+describe('AuditLog - Error Handling', () => {
+  let mockClient: jest.Mocked<Client>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    
+    mockClient = {
+      getDomain: jest.fn().mockReturnValue('https://dev.api.ibm.com/ghgemissions/test/'),
+      refreshToken: jest.fn().mockResolvedValue(undefined),
+      getAuthHeader: jest.fn().mockReturnValue({ Authorization: 'Bearer mock-token' }),
+      getClientId: jest.fn().mockReturnValue('test-client-id'),
+      getClientSource: jest.fn().mockReturnValue('node-sdk'),
+    } as any;
+
+    (Client.getInstance as jest.Mock).mockReturnValue(mockClient);
+  });
+
+  it('should handle 409 Conflict gracefully when configuration is unchanged', async () => {
+    const mockError = {
+      isAxiosError: true,
+      response: {
+        status: 409,
+        statusText: 'Conflict',
+        data: {
+          logRequest: true,
+          logResponse: false,
+          message: 'No change in audit log configuration'
+        },
+        headers: {},
+        config: {}
+      }
+    };
+
+    // Mock makeApiRequest to throw a 409 error
+    (request.makeApiRequest as jest.Mock).mockRejectedValue(mockError);
+
+    const payload = { logRequest: true, logResponse: false };
+    const result = await updateAuditConfig(payload);
+
+    expect(result).toEqual({
+      logRequest: true,
+      logResponse: false,
+      message: 'No change in audit log configuration'
+    });
+  });
+
+  it('should throw error for non-409 status codes', async () => {
+    const mockError = {
+      isAxiosError: true,
+      response: {
+        status: 500,
+        statusText: 'Internal Server Error',
+        data: { message: 'Server error' },
+        headers: {},
+        config: {}
+      }
+    };
+
+    (request.makeApiRequest as jest.Mock).mockRejectedValue(mockError);
+
+    const payload = { logRequest: true, logResponse: false };
+    
+    await expect(updateAuditConfig(payload)).rejects.toEqual(mockError);
+  });
+
+  it('should return updated configuration on successful update', async () => {
+    const mockResponse = {
+      logRequest: false,
+      logResponse: true,
+      message: 'Audit log configuration updated successfully'
+    };
+
+    (request.makeApiRequest as jest.Mock).mockResolvedValue(mockResponse);
+
+    const payload = { logRequest: false, logResponse: true };
+    const result = await updateAuditConfig(payload);
+
+    expect(result).toEqual(mockResponse);
+  });
+
+  it('should throw error for non-Axios errors', async () => {
+    const mockError = new Error('Network error');
+
+    (request.makeApiRequest as jest.Mock).mockRejectedValue(mockError);
+
+    const payload = { logRequest: true, logResponse: false };
+    
+    await expect(updateAuditConfig(payload)).rejects.toThrow('Network error');
+  });
+
+  it('should handle 400 Bad Request with error message from API', async () => {
+    const mockError = {
+      isAxiosError: true,
+      response: {
+        status: 400,
+        statusText: 'Bad Request',
+        data: {
+          message: 'Invalid payload: logRequest must be a boolean'
+        },
+        headers: {},
+        config: {}
+      }
+    };
+
+    (request.makeApiRequest as jest.Mock).mockRejectedValue(mockError);
+
+    const payload = { logRequest: true, logResponse: false };
+    
+    await expect(updateAuditConfig(payload)).rejects.toThrow('Invalid payload: logRequest must be a boolean');
+  });
+
+  it('should handle 403 Forbidden with error message from API', async () => {
+    const mockError = {
+      isAxiosError: true,
+      response: {
+        status: 403,
+        statusText: 'Forbidden',
+        data: {
+          message: 'User not authorized to make the request. Please contact the organisation administrator.'
+        },
+        headers: {},
+        config: {}
+      }
+    };
+
+    (request.makeApiRequest as jest.Mock).mockRejectedValue(mockError);
+
+    const payload = { logRequest: true, logResponse: false };
+    
+    await expect(updateAuditConfig(payload)).rejects.toThrow('User not authorized to make the request. Please contact the organisation administrator.');
+  });
+});
+
+describe('AuditLog - getAuditConfig Error Handling', () => {
+  let mockClient: jest.Mocked<Client>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    
+    mockClient = {
+      getDomain: jest.fn().mockReturnValue('https://dev.api.ibm.com/ghgemissions/test/'),
+      refreshToken: jest.fn().mockResolvedValue(undefined),
+      getAuthHeader: jest.fn().mockReturnValue({ Authorization: 'Bearer mock-token' }),
+      getClientId: jest.fn().mockReturnValue('test-client-id'),
+      getClientSource: jest.fn().mockReturnValue('node-sdk'),
+    } as any;
+
+    (Client.getInstance as jest.Mock).mockReturnValue(mockClient);
+  });
+
+  it('should return audit config on successful request', async () => {
+    const mockResponse = {
+      logRequest: true,
+      logResponse: false,
+      message: 'Current audit log configuration'
+    };
+
+    (request.makeApiRequest as jest.Mock).mockResolvedValue(mockResponse);
+
+    const result = await getAuditConfig();
+
+    expect(result).toEqual(mockResponse);
+  });
+
+  it('should handle 403 Forbidden with error message from API', async () => {
+    const mockError = {
+      isAxiosError: true,
+      response: {
+        status: 403,
+        statusText: 'Forbidden',
+        data: {
+          message: 'User not authorized to make the request. Please contact the organisation administrator.'
+        },
+        headers: {},
+        config: {}
+      }
+    };
+
+    (request.makeApiRequest as jest.Mock).mockRejectedValue(mockError);
+    
+    await expect(getAuditConfig()).rejects.toThrow('User not authorized to make the request. Please contact the organisation administrator.');
+  });
+
+  it('should throw error for other status codes', async () => {
+    const mockError = {
+      isAxiosError: true,
+      response: {
+        status: 500,
+        statusText: 'Internal Server Error',
+        data: { message: 'Server error' },
+        headers: {},
+        config: {}
+      }
+    };
+
+    (request.makeApiRequest as jest.Mock).mockRejectedValue(mockError);
+    
+    await expect(getAuditConfig()).rejects.toEqual(mockError);
+  });
+
+  it('should throw error for non-Axios errors', async () => {
+    const mockError = new Error('Network error');
+
+    (request.makeApiRequest as jest.Mock).mockRejectedValue(mockError);
+    
+    await expect(getAuditConfig()).rejects.toThrow('Network error');
+  });
+});

package/test/mocks/AttributionRequest.ts

@@ -0,0 +1,23 @@
+import { CommonRequest } from '../../src/interfaces/Api';
+
+const attributionPayload: CommonRequest = {
+  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 default attributionPayload;

package/test/mocks/EconomicActivityAttributionRequest.ts

@@ -0,0 +1,22 @@
+import { CommonRequest } from '../../src/interfaces/Api';
+
+const economicActivityAttributionPayload: CommonRequest = {
+  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,
+};
+
+export default economicActivityAttributionPayload;

package/test/mocks/PhysicalActivityEVICRequest.ts

@@ -0,0 +1,22 @@
+import { CommonRequest } from '../../src/interfaces/Api';
+
+const physicalActivityEVICPayload: CommonRequest = {
+  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,
+};
+
+export default physicalActivityEVICPayload;

package/test/mocks/PhysicalActivityRequest.ts

@@ -0,0 +1,23 @@
+import { CommonRequest } from '../../src/interfaces/Api';
+
+const physicalActivityPayload: CommonRequest = {
+  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,
+};
+
+export default physicalActivityPayload;

package/test/mocks/SearchRequest.ts

@@ -16,4 +16,52 @@ const SearchPayload: SearchRequest = {
   }
 };
 
+// Search payload with unit parameter
+export const SearchPayloadWithUnit: SearchRequest = {
+  location: {
+    "country": "usa"
+  },
+  time: {
+    date: "2025-06-10",
+  },
+  activity: {
+    "search": "electricity",
+    "unit": "kWh"
+  }
+};
+
+// Search payload with scope parameter
+export const SearchPayloadWithScope: SearchRequest = {
+  location: {
+    "country": "usa"
+  },
+  time: {
+    date: "2025-06-10",
+  },
+  activity: {
+    "search": "natural gas",
+    "scope": "1"
+  }
+};
+
+// Search payload with both unit and scope parameters
+export const SearchPayloadWithBoth: SearchRequest = {
+  location: {
+    "country": "usa",
+    "stateProvince": "california"
+  },
+  time: {
+    date: "2025-06-10",
+  },
+  activity: {
+    "search": "electricity",
+    "unit": "MWh",
+    "scope": "2"
+  },
+  pagination:{
+    "page": 1,
+    "size": 10
+  }
+};
+
 export default SearchPayload;