emissions-api-sdk 1.0.13 → 1.0.14

package/src/api/AuditExport.ts

@@ -0,0 +1,90 @@
+import { Buffer } from "node:buffer";
+import { Client } from "../Client";
+import {
+  AUDIT_EXPORT_API_PATH,
+  AUDIT_EXPORT_DOWNLOAD_API_PATH,
+  AUDIT_EXPORT_STATUS_API_PATH,
+  GET,
+  POST,
+} from "../Constants";
+import {
+  AuditExportRequest,
+  AuditExportResponse,
+  AuditExportStatusResponse,
+} from "../interfaces/response/AuditExportResponse";
+import { makeApiRequest } from "../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"
+ * });
+ */
+export async function trigger(
+  payload: AuditExportRequest
+): Promise<AuditExportResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + AUDIT_EXPORT_API_PATH;
+
+  return makeApiRequest<AuditExportResponse>({
+    method: 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);
+ */
+export async function getStatus(
+  requestId: string
+): Promise<AuditExportStatusResponse> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + AUDIT_EXPORT_STATUS_API_PATH;
+
+  return makeApiRequest<AuditExportStatusResponse>({
+    method: 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);
+ */
+export async function download(requestId: string): Promise<Buffer> {
+  const client = Client.getInstance();
+  const url = client.getDomain() + AUDIT_EXPORT_DOWNLOAD_API_PATH;
+
+  return makeApiRequest<Buffer>({
+    method: GET,
+    url,
+    params: { requestId },
+    responseType: "arraybuffer",
+  });
+}

package/src/api/EconomicActivity.ts

@@ -53,6 +53,51 @@ import { makeApiRequest } from "../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);
  */
 
 export async function calculate(

package/src/api/Factor.ts

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

package/src/api/RealEstate.ts

@@ -52,7 +52,8 @@ import { makeApiRequest } from "../request";
     },
     "includeDetails": true
   };
- */
+* const resultWithAttribution = await calculate(requestWithAttribution);
+*/
 
 export async function calculate(
   payload: CommonRequest

package/src/index.ts

@@ -14,6 +14,7 @@ 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
@@ -43,4 +44,11 @@ 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 { AuditLogResponse, AuditLogRequest } from './interfaces/response/AuditLogResponse';
+export { AuditLogResponse, AuditLogRequest } from './interfaces/response/AuditLogResponse';
+export {
+  AuditExportRequest,
+  AuditExportResponse,
+  AuditExportStatus,
+  AuditExportStatusResponse,
+  AuditExportLinks
+} from './interfaces/response/AuditExportResponse';

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

@@ -16,5 +16,6 @@ export interface ActivityRequest {
 
     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/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",
+    });
+  });
+});