emissions-api-sdk 1.0.13 → 1.0.14

package/dist/types/Constants.d.ts

@@ -14,6 +14,9 @@ export declare const ECONOMIC_ACTIVITY_API_PATH = "/v3/carbon/economic-activity"
 export declare const REAL_ESTATE_API_PATH = "/v3/carbon/real-estate";
 export declare const PHYSICAL_ACTIVITY_API_PATH = "/v3/carbon/physical-activity";
 export declare const AUDIT_LOG_API_PATH = "/v3/carbon/admin/audit-log";
+export declare const AUDIT_EXPORT_API_PATH = "/v3/carbon/audit";
+export declare const AUDIT_EXPORT_STATUS_API_PATH = "/v3/carbon/audit/status";
+export declare const AUDIT_EXPORT_DOWNLOAD_API_PATH = "/v3/carbon/audit/download";
 export declare const TYPE_RECOMMENDER_API_PATH = "/v3/carbon/recommender/type/search";
 export declare const USAGE_API = "/v3/carbon/usage";
 export declare const METADATA_TYPES_ENDPOINT = "/v3/carbon/metadata/types";

package/dist/types/api/AuditExport.d.ts

@@ -0,0 +1,42 @@
+import { Buffer } from "node:buffer";
+import { AuditExportRequest, AuditExportResponse, AuditExportStatusResponse } from "../interfaces/response/AuditExportResponse";
+/**
+ * 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 declare function trigger(payload: AuditExportRequest): Promise<AuditExportResponse>;
+/**
+ * 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 declare function getStatus(requestId: string): Promise<AuditExportStatusResponse>;
+/**
+ * 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 declare function download(requestId: string): Promise<Buffer>;

package/dist/types/api/EconomicActivity.d.ts

@@ -49,5 +49,50 @@ import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResp
     "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 declare function calculate(payload: CommonRequest): Promise<EmissionResponse | EmissionResponseWithDetails>;

package/dist/types/api/Factor.d.ts

@@ -63,11 +63,8 @@ export declare function retrieveFactor(payload: FactorRequest): Promise<FactorRe
  * @example
  * // Search without cross-encoder reranking
  * const searchWithoutReranker = {
-    "time":{
-      "date": "2020-06-10"
-    },
     "activity": {
-      "search" : "travel"
+      "search": "travel"
     },
     "location": {
       "country": "USA"

package/dist/types/api/RealEstate.d.ts

@@ -48,5 +48,6 @@ import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResp
     },
     "includeDetails": true
   };
- */
+* const resultWithAttribution = await calculate(requestWithAttribution);
+*/
 export declare function calculate(payload: CommonRequest): Promise<EmissionResponse | EmissionResponseWithDetails>;

package/dist/types/index.d.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';
 export { Attribution } from './interfaces/common';
 export { AreaResponse, Location as LocationInfo } from './interfaces/response/AreaResponse';
@@ -27,3 +28,4 @@ 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 { AuditExportRequest, AuditExportResponse, AuditExportStatus, AuditExportStatusResponse, AuditExportLinks } from './interfaces/response/AuditExportResponse';

package/dist/types/interfaces/Config.d.ts

@@ -1,4 +1,4 @@
-import { Method } from "axios";
+import { Method, ResponseType } from "axios";
 /**
  * Configuration for making HTTP requests.
  * @interface RequestConfig
@@ -24,6 +24,10 @@ 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;
 }
 /**
  * Configuration for initializing a client instance.

package/dist/types/interfaces/response/AuditExportResponse.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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/dist/types/interfaces/response/TypeRecommenderResponse.d.ts

@@ -11,5 +11,6 @@ export interface ActivityRequest {
     activityUnit: string[];
     activityDescription: string;
     confidence: number;
+    /** Distinct GHG Protocol scopes associated with the activity type. */
     scope?: string[];
 }

package/docs/_sources/getting_started.rst.txt

@@ -248,8 +248,7 @@ The SDK supports automatic currency conversion for API methods that accept monet
 Currency conversion is available for the following calculation methods:
 
 - ``EconomicActivity.calculate()``
-- ``RealEstate.calculate()``
-- ``PhysicalActivity.calculate()``
+- ``Calculation.calculate()``
 
 Supported Currencies
 ~~~~~~~~~~~~~~~~~~~~
@@ -626,3 +625,228 @@ The exchange rate database is automatically synchronized with the Treasury API t
 
 
 - ``source``: Source citation and license information
+
+Finance Emissions APIs
+----------------------
+
+The SDK supports three scope 3 finance-based emission APIs: **Real Estate**, **Physical Activity**, and **Economic Activity**. Each supports optional PCAF attribution to proportionally allocate emissions.
+
+Real Estate
+~~~~~~~~~~~
+
+Real Estate calculates scope 3 emissions from commercial and residential property. Attribution uses ``propertyValue`` to compute an attribution factor.
+
+**Without attribution:**
+
+.. code-block:: javascript
+
+  const result = await RealEstate.calculate({
+    "time": { "date": "2022-01-01" },
+    "location": { "country": "usa", "stateProvince": "new york" },
+    "activity": {
+      "type": "Commercial Real Estate:Office",
+      "value": 123456.0,
+      "unit": "m2"
+    },
+    "includeDetails": false
+  });
+
+**With attribution (property value based):**
+
+.. code-block:: javascript
+
+  const result = await RealEstate.calculate({
+    "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
+  });
+
+.. note::
+
+   Real estate attribution only accepts ``propertyValue``. Using ``totalEquity``, ``totalDebt``, ``evic``, or ``revenue`` will result in a 400 error.
+
+Physical Activity
+~~~~~~~~~~~~~~~~~
+
+Physical Activity calculates scope 3 emissions from physical activities. Attribution supports two methods: equity/debt for private companies, or EVIC for listed companies.
+
+**Without attribution:**
+
+.. code-block:: javascript
+
+  const result = await PhysicalActivity.calculate({
+    "time": { "date": "2022-01-01" },
+    "location": { "country": "usa", "stateProvince": "new york" },
+    "activity": {
+      "type": "Physical Activity Type",
+      "value": 123456.0,
+      "unit": "kg"
+    },
+    "includeDetails": false
+  });
+
+**With attribution (equity/debt — private companies):**
+
+.. code-block:: javascript
+
+  const result = await PhysicalActivity.calculate({
+    "time": { "date": "2022-01-01" },
+    "location": { "country": "usa", "stateProvince": "new york" },
+    "activity": {
+      "type": "Physical Activity Type",
+      "value": 123456.0,
+      "unit": "kg"
+    },
+    "attribution": {
+      "outstandingAmount": 1000000.0,
+      "totalEquity": 3000000.0,
+      "totalDebt": 2000000.0
+    },
+    "includeDetails": true
+  });
+
+**With attribution (EVIC — listed companies):**
+
+.. code-block:: javascript
+
+  const result = await PhysicalActivity.calculate({
+    "time": { "date": "2022-01-01" },
+    "location": { "country": "usa", "stateProvince": "new york" },
+    "activity": {
+      "type": "Physical Activity Type",
+      "value": 123456.0,
+      "unit": "kg"
+    },
+    "attribution": {
+      "outstandingAmount": 1000000.0,
+      "evic": 10000000.0
+    },
+    "includeDetails": true
+  });
+
+.. note::
+
+   Physical activity attribution does not accept ``propertyValue`` or ``revenue``. Use ``totalEquity + totalDebt`` for private companies, or ``evic`` for listed companies — not both.
+
+Economic Activity
+~~~~~~~~~~~~~~~~~
+
+Economic Activity calculates scope 3 spend-based emissions. Attribution supports equity/debt, EVIC, or revenue-based allocation.
+
+**Without attribution:**
+
+.. code-block:: javascript
+
+  const result = await EconomicActivity.calculate({
+    "time": { "date": "2022-01-01" },
+    "location": { "country": "usa", "stateProvince": "new york" },
+    "activity": {
+      "type": "Accomodation",
+      "value": 123456.0,
+      "unit": "usd"
+    },
+    "includeDetails": false
+  });
+
+**With attribution (revenue based):**
+
+.. code-block:: javascript
+
+  const result = await EconomicActivity.calculate({
+    "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
+  });
+
+**With attribution (equity/debt — private companies):**
+
+.. code-block:: javascript
+
+  const result = await EconomicActivity.calculate({
+    "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
+  });
+
+**With attribution (EVIC — listed companies):**
+
+.. code-block:: javascript
+
+  const result = await EconomicActivity.calculate({
+    "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
+  });
+
+.. note::
+
+   ``propertyValue`` is not supported for economic activity. ``totalEquity`` and ``totalDebt`` must always be provided together.
+
+Attribution Summary
+~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 14 20 12 12 12
+
+   * - API
+     - ``propertyValue``
+     - ``totalEquity`` + ``totalDebt``
+     - ``evic``
+     - ``revenue``
+     - ``outstandingAmount``
+   * - Real Estate
+     - ✓
+     - ✗
+     - ✗
+     - ✗
+     - Required
+   * - Physical Activity
+     - ✗
+     - ✓
+     - ✓
+     - ✗
+     - Required
+   * - Economic Activity
+     - ✗
+     - ✓
+     - ✓
+     - ✓
+     - Required

package/docs/_sources/index.rst.txt

@@ -29,6 +29,7 @@ Supported Emission Types
 * **Transportation & distribution** – logistics and supply chain activities
 * **Real Estate** – emissions from commercial and residential properties
 * **Economic Activity** – spend-based emissions from business activities
+* **Physical Activity** – scope 3 emissions from physical activities with attribution for private companies (equity/debt or EVIC-based)
 * **Generic** – custom emission calculations
 
 The SDK is designed for embedding emission calculations in applications, building sustainability dashboards, automating large-scale datasets, and tracking carbon footprints.
@@ -41,3 +42,4 @@ Additional capabilities
 * **Factor Search API** – search for emission factors with unit and scope filtering, with optional reranker control
 * **Usage API** – retrieve organization billing-period or historical usage
 * **Audit Log API** – manage whether API requests and responses are stored for auditing
+* **Audit Export API** – export, monitor, and download organization audit data

package/docs/_sources/reference.rst.txt

@@ -32,6 +32,8 @@ API
 .. js:autofunction:: RealEstate.calculate
 
 .. js:autofunction:: EconomicActivity.calculate
+   
+.. js:autofunction:: PhysicalActivity.calculate
 
 Type Recommender API
 ====================
@@ -50,6 +52,18 @@ Organizations can disable storage if they don't need their API calls to be audit
 .. js:autofunction:: AuditLog.updateAuditConfig
 
 
+Audit Export API
+================
+
+The Audit Export API asynchronously generates an audit-data ZIP archive for an admin user. Call ``trigger`` to create an export, ``getStatus`` until it is complete, and ``download`` to retrieve the archive.
+
+.. js:autofunction:: AuditExport.trigger
+
+.. js:autofunction:: AuditExport.getStatus
+
+.. js:autofunction:: AuditExport.download
+
+
 Global Metadata API
 ====================
 
@@ -139,3 +153,11 @@ Interfaces
 .. js:autoclass:: TypeRecommenderResponse.TypeRecommenderResponse
 
 .. js:autoclass:: TypeRecommenderResponse.ActivityRequest
+
+.. js:autoclass:: AuditExportResponse.AuditExportRequest
+
+.. js:autoclass:: AuditExportResponse.AuditExportResponse
+
+.. js:autoclass:: AuditExportResponse.AuditExportStatusResponse
+
+.. js:autoclass:: AuditExportResponse.AuditExportLinks

package/docs/genindex.html

@@ -246,7 +246,7 @@
           
 <section class="genindex-section">
   <h1 id="index">Index</h1>
-  <div class="genindex-jumpbox"><a href="#A"><strong>A</strong></a> | <a href="#C"><strong>C</strong></a> | <a href="#E"><strong>E</strong></a> | <a href="#F"><strong>F</strong></a> | <a href="#L"><strong>L</strong></a> | <a href="#M"><strong>M</strong></a> | <a href="#R"><strong>R</strong></a> | <a href="#S"><strong>S</strong></a> | <a href="#T"><strong>T</strong></a> | <a href="#U"><strong>U</strong></a></div>
+  <div class="genindex-jumpbox"><a href="#A"><strong>A</strong></a> | <a href="#C"><strong>C</strong></a> | <a href="#E"><strong>E</strong></a> | <a href="#F"><strong>F</strong></a> | <a href="#L"><strong>L</strong></a> | <a href="#M"><strong>M</strong></a> | <a href="#P"><strong>P</strong></a> | <a href="#R"><strong>R</strong></a> | <a href="#S"><strong>S</strong></a> | <a href="#T"><strong>T</strong></a> | <a href="#U"><strong>U</strong></a></div>
 </section>
 <section id="A" class="genindex-section">
   <h2>A</h2>
@@ -264,13 +264,27 @@
 </li>
         <li><a href="reference.html#Api.GenericCalculationRequestWithoutFactorId">Api.GenericCalculationRequestWithoutFactorId() (interface)</a>
 </li>
-    </ul></td>
-    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#Api.LocationRequestWithFactorId">Api.LocationRequestWithFactorId() (interface)</a>
 </li>
         <li><a href="reference.html#Api.LocationRequestWithoutFactorId">Api.LocationRequestWithoutFactorId() (interface)</a>
 </li>
         <li><a href="reference.html#Api.SearchRequest">Api.SearchRequest() (interface)</a>
+</li>
+        <li><a href="reference.html#AuditExport.download">AuditExport.download() (AuditExport method)</a>
+</li>
+    </ul></td>
+    <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#AuditExport.getStatus">AuditExport.getStatus() (AuditExport method)</a>
+</li>
+        <li><a href="reference.html#AuditExport.trigger">AuditExport.trigger() (AuditExport method)</a>
+</li>
+        <li><a href="reference.html#AuditExportResponse.AuditExportLinks">AuditExportResponse.AuditExportLinks() (interface)</a>
+</li>
+        <li><a href="reference.html#AuditExportResponse.AuditExportRequest">AuditExportResponse.AuditExportRequest() (interface)</a>
+</li>
+        <li><a href="reference.html#AuditExportResponse.AuditExportResponse">AuditExportResponse.AuditExportResponse() (interface)</a>
+</li>
+        <li><a href="reference.html#AuditExportResponse.AuditExportStatusResponse">AuditExportResponse.AuditExportStatusResponse() (interface)</a>
 </li>
         <li><a href="reference.html#AuditLog.getAuditConfig">AuditLog.getAuditConfig() (AuditLog method)</a>
 </li>
@@ -396,6 +410,16 @@
   </tr></table>
 </section>
 
+<section id="P" class="genindex-section">
+  <h2>P</h2>
+  <table style="width: 100%" class="indextable genindextable"><tr>
+    <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#PhysicalActivity.calculate">PhysicalActivity.calculate() (PhysicalActivity method)</a>
+</li>
+    </ul></td>
+  </tr></table>
+</section>
+
 <section id="R" class="genindex-section">
   <h2>R</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>