emissions-api-sdk 1.0.12 → 1.0.14

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

@@ -3,6 +3,7 @@ import { EmissionResponse } from "../interfaces/response/EmissionResponse";
 import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResponseWithDetails";
 /**
  * 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
@@ -10,6 +11,7 @@ import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResp
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
+ * // Basic economic activity request
  * const request = {
     "time": {
       "date": "2025-01-04"
@@ -25,5 +27,72 @@ import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResp
     "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);
+ *
+ * @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

@@ -42,6 +42,9 @@ export declare function retrieveFactor(payload: FactorRequest): Promise<FactorRe
  * @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 = {
@@ -58,6 +61,19 @@ export declare function retrieveFactor(payload: FactorRequest): Promise<FactorRe
  * const results = await search(searchRequest);
  *
  * @example
+ * // Search without cross-encoder reranking
+ * const searchWithoutReranker = {
+    "activity": {
+      "search": "travel"
+    },
+    "location": {
+      "country": "USA"
+    },
+    "enableReranker": false
+  };
+ * const results = await search(searchWithoutReranker);
+ *
+ * @example
  * // Search with optional unit parameter
  * const searchWithUnit = {
     "time":{

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

@@ -0,0 +1,76 @@
+import { CommonRequest } from "../interfaces/Api";
+import { EmissionResponse } from "../interfaces/response/EmissionResponse";
+import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResponseWithDetails";
+/**
+ * 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 declare function calculate(payload: CommonRequest): Promise<EmissionResponse | EmissionResponseWithDetails>;

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

@@ -10,6 +10,7 @@ import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResp
  * @throws {Error} May throw an error if the API request fails
  *
  * @example
+ * // Basic request without attribution
  * const request = {
     "time": {
       "date": "2025-01-04"
@@ -25,5 +26,28 @@ import { EmissionResponseWithDetails } from "../interfaces/response/EmissionResp
     "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 declare function calculate(payload: CommonRequest): Promise<EmissionResponse | EmissionResponseWithDetails>;

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

@@ -1,13 +1,18 @@
 import { SearchRequest } from "../interfaces/Api";
 import { TypeRecommenderResponse } from "../interfaces/response/TypeRecommenderResponse";
 /**
- * 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({
@@ -51,6 +56,18 @@ import { TypeRecommenderResponse } from "../interfaces/response/TypeRecommenderR
   });
  *
  * @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/dist/types/index.d.ts

@@ -10,9 +10,13 @@ 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';
+export { Attribution } from './interfaces/common';
 export { AreaResponse, Location as LocationInfo } from './interfaces/response/AreaResponse';
 export { EmissionResponse } from './interfaces/response/EmissionResponse';
 export { EmissionResponseWithDetails, FactorDetails, FactorSetDetails, IncludeDetails } from './interfaces/response/EmissionResponseWithDetails';
@@ -23,3 +27,5 @@ 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 { AuditExportRequest, AuditExportResponse, AuditExportStatus, AuditExportStatusResponse, AuditExportLinks } from './interfaces/response/AuditExportResponse';

package/dist/types/interfaces/Api.d.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.
  * Derived from the Activity type but makes the 'type' and 'unit' properties optional
@@ -119,6 +119,11 @@ 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.
@@ -137,6 +142,11 @@ 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.
@@ -254,6 +264,12 @@ export interface SearchRequest {
      * Used to limit the number of results and implement paging.
      */
     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;
 }
 /**
  * Union type representing either a factor request with or without a specific factor ID.

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/common.d.ts

@@ -158,3 +158,43 @@ 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/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/AuditLogResponse.d.ts

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

@@ -11,4 +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/authentication.rst.txt

@@ -10,17 +10,39 @@ The IBM Envizi - Emissions API Node.js SDK uses OAuth 2.0 Bearer Tokens for auth
 Authentication Methods
 ----------------------
 
-The SDK provides two authentication methods:
+The SDK provides three authentication methods:
 
-API Key Authentication (Recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Personal Access Token (PAT) Authentication (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This method uses a personal access token directly:
+
+.. code-block:: javascript
+
+    import { Client } from 'emissions-api-sdk';
+
+    await Client.getClient({
+      patToken: process.env.ENVIZI_PAT_TOKEN,
+      clientId: process.env.ENVIZI_CLIENT_ID
+    });
+
+**Required parameters:**
+    - ``patToken``: Your personal access token
+    - ``clientId``: Your client identifier
+
+.. note::
+
+   When using a PAT token, do not provide ``orgId``.
+
+API Key Authentication
+~~~~~~~~~~~~~~~~~~~~~~
 
 This method automatically handles token generation and refreshing:
 
 .. code-block:: javascript
 
     import { Client } from 'emissions-api-sdk';
-    
+
     await Client.getClient({
       apiKey: process.env.ENVIZI_API_KEY,
       clientId: process.env.ENVIZI_CLIENT_ID,