emissions-api-sdk 1.0.12 → 1.0.14

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,7 +30,30 @@ 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
+  };
+* const resultWithAttribution = await calculate(requestWithAttribution);
+*/
 
 export async function calculate(
   payload: CommonRequest

package/src/api/TypeRecommender.ts

@@ -5,13 +5,18 @@ 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({
@@ -55,6 +60,18 @@ import { makeApiRequest } from "../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": {

package/src/index.ts

@@ -10,10 +10,16 @@ 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 * as AuditExport from './api/AuditExport';
 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 +43,12 @@ 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';
+export {
+  AuditExportRequest,
+  AuditExportResponse,
+  AuditExportStatus,
+  AuditExportStatusResponse,
+  AuditExportLinks
+} from './interfaces/response/AuditExportResponse';

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/Config.ts

@@ -1,4 +1,4 @@
-import { Method } from "axios";
+import { Method, ResponseType } from "axios";
 
 /**
  * Configuration for making HTTP requests.
@@ -29,6 +29,11 @@ export interface RequestConfig {
    * Optional HTTP headers to be included with the request.
    */
   headers?: Record<string, string>;
+
+  /**
+   * Optional response type expected from the API.
+   */
+  responseType?: ResponseType;
 }
 
 /**

package/src/interfaces/common.ts

@@ -184,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/AuditExportResponse.ts

@@ -0,0 +1,88 @@
+/**
+ * Request body used to trigger an audit data export.
+ *
+ * @interface AuditExportRequest
+ */
+export interface AuditExportRequest {
+  /** Inclusive start date in yyyy-MM-dd format. */
+  fromDate: string;
+
+  /** Inclusive end date in yyyy-MM-dd format. */
+  toDate: string;
+
+  /** Optional case-insensitive endpoint filter. */
+  apiName?: string;
+}
+
+/**
+ * Processing states for an audit export.
+ */
+export type AuditExportStatus =
+  | "QUEUED"
+  | "IN_PROGRESS"
+  | "COMPLETED"
+  | "FAILED"
+  | "EXPIRED";
+
+/**
+ * Follow-up links returned by the audit export API.
+ *
+ * @interface AuditExportLinks
+ */
+export interface AuditExportLinks {
+  /** URL for retrieving the export status. */
+  status?: string;
+
+  /** URL for downloading a completed export. */
+  download?: string;
+}
+
+/**
+ * Response returned when an audit export is accepted.
+ *
+ * @interface AuditExportResponse
+ */
+export interface AuditExportResponse {
+  /** Unique identifier used to retrieve the export status and download. */
+  requestId: string;
+
+  /** Current processing state. A newly accepted export is QUEUED. */
+  status: AuditExportStatus;
+
+  /** Human-readable result message. */
+  message?: string;
+
+  /** ISO-8601 timestamp for when the export was submitted. */
+  submittedAt?: string;
+
+  /** Links for retrieving the export status and download. */
+  links?: AuditExportLinks;
+}
+
+/**
+ * Response returned when checking an audit export's status.
+ *
+ * @interface AuditExportStatusResponse
+ */
+export interface AuditExportStatusResponse {
+  /** Unique identifier returned when the export was triggered. */
+  requestId: string;
+
+  /** Current processing state. */
+  status: AuditExportStatus;
+
+  /** ISO-8601 timestamp for when the export was submitted. */
+  submittedAt?: string;
+
+  /** ISO-8601 timestamp for when processing completed. */
+  completedAt?: string;
+
+  /** ISO-8601 timestamp after which the completed export is unavailable. */
+  expiresAt?: string;
+
+  /** Download link when the export is completed. */
+  links?: Pick<AuditExportLinks, "download">;
+
+  /** Human-readable failure or expiry message. */
+  message?: string;
+}

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,7 @@ export interface ActivityRequest {
     activityDescription: string;
 
     confidence: number;
+
+    /** Distinct GHG Protocol scopes associated with the activity type. */
+    scope?: string[];
 }

package/src/request.ts

@@ -36,6 +36,7 @@ export async function makeApiRequest<T>(config: RequestConfig): Promise<T> {
     url: config.url,
     data: config.data,
     params: config.params,
+    responseType: config.responseType,
     headers: {
       ...client.getAuthHeader(),
       ...config.headers,

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/auditExport.test.ts

@@ -0,0 +1,68 @@
+import { Buffer } from "buffer";
+import { Client } from "../src/Client";
+import { download, getStatus, trigger } from "../src/api/AuditExport";
+import {
+  AUDIT_EXPORT_API_PATH,
+  AUDIT_EXPORT_DOWNLOAD_API_PATH,
+  AUDIT_EXPORT_STATUS_API_PATH,
+  GET,
+  POST,
+} from "../src/Constants";
+import * as request from "../src/request";
+
+jest.mock("../src/request");
+jest.mock("../src/Client");
+
+describe("AuditExport", () => {
+  const domain = "https://dev.api.ibm.com/ghgemissions/test";
+  const requestId = "tenant-uuid/20250101-20250331-location";
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (Client.getInstance as jest.Mock).mockReturnValue({
+      getDomain: jest.fn().mockReturnValue(domain),
+    });
+  });
+
+  it("triggers an audit export", async () => {
+    const payload = {
+      fromDate: "2025-01-01",
+      toDate: "2025-03-31",
+      apiName: "location",
+    };
+    const response = { requestId, status: "QUEUED" };
+    (request.makeApiRequest as jest.Mock).mockResolvedValue(response);
+
+    await expect(trigger(payload)).resolves.toEqual(response);
+    expect(request.makeApiRequest).toHaveBeenCalledWith({
+      method: POST,
+      url: `${domain}${AUDIT_EXPORT_API_PATH}`,
+      data: payload,
+    });
+  });
+
+  it("gets an audit export status", async () => {
+    const response = { requestId, status: "COMPLETED" };
+    (request.makeApiRequest as jest.Mock).mockResolvedValue(response);
+
+    await expect(getStatus(requestId)).resolves.toEqual(response);
+    expect(request.makeApiRequest).toHaveBeenCalledWith({
+      method: GET,
+      url: `${domain}${AUDIT_EXPORT_STATUS_API_PATH}`,
+      params: { requestId },
+    });
+  });
+
+  it("downloads a completed audit export as binary data", async () => {
+    const response = Buffer.from("zip-content");
+    (request.makeApiRequest as jest.Mock).mockResolvedValue(response);
+
+    await expect(download(requestId)).resolves.toBe(response);
+    expect(request.makeApiRequest).toHaveBeenCalledWith({
+      method: GET,
+      url: `${domain}${AUDIT_EXPORT_DOWNLOAD_API_PATH}`,
+      params: { requestId },
+      responseType: "arraybuffer",
+    });
+  });
+});