emissions-api-sdk 1.0.11 → 1.0.13

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

@@ -42,17 +42,88 @@ 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 = {
     "time":{
       "date": "2020-06-10"
     },
     "activity": {
-      "search" : "travel"},
+      "search" : "travel"
+    },
     "location": {
       "country": "USA"
     }
   };
  * const results = await search(searchRequest);
+ *
+ * @example
+ * // Search without cross-encoder reranking
+ * const searchWithoutReranker = {
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search" : "travel"
+    },
+    "location": {
+      "country": "USA"
+    },
+    "enableReranker": false
+  };
+ * const results = await search(searchWithoutReranker);
+ *
+ * @example
+ * // Search with optional unit parameter
+ * const searchWithUnit = {
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search": "electricity",
+      "unit": "kWh"
+    },
+    "location": {
+      "country": "USA"
+    }
+  };
+ * const results = await search(searchWithUnit);
+ *
+ * @example
+ * // Search with optional scope parameter
+ * const searchWithScope = {
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search": "natural gas",
+      "scope": "1"
+    },
+    "location": {
+      "country": "USA"
+    }
+  };
+ * const results = await search(searchWithScope);
+ *
+ * @example
+ * // Search with both unit and scope parameters
+ * const searchWithBoth = {
+    "time":{
+      "date": "2020-06-10"
+    },
+    "activity": {
+      "search": "electricity",
+      "unit": "MWh",
+      "scope": "2"
+    },
+    "location": {
+      "country": "USA",
+      "stateProvince": "california"
+    }
+  };
+ * const results = await search(searchWithBoth);
  */
 export declare function search(payload: SearchRequest): Promise<SearchResponse>;

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,27 @@ 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
+  };
  */
 export declare function calculate(payload: CommonRequest): Promise<EmissionResponse | EmissionResponseWithDetails>;

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

@@ -1,14 +1,20 @@
 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({
     "location": {
       "country": "usa"
@@ -19,6 +25,7 @@ import { TypeRecommenderResponse } from "../interfaces/response/TypeRecommenderR
   });
 
  * @example
+ * // Search with time and pagination
  * const result = await search({
     "location": {
       "country": "usa",
@@ -37,6 +44,7 @@ import { TypeRecommenderResponse } from "../interfaces/response/TypeRecommenderR
   });
  
  * @example
+ * // Search with power grid
  * const result = await search({
     "location": {
       "country": "usa",
@@ -46,5 +54,62 @@ import { TypeRecommenderResponse } from "../interfaces/response/TypeRecommenderR
       "search": "renewable energy"
     }
   });
+ *
+ * @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": {
+      "country": "usa"
+    },
+    "activity": {
+      "search": "electricity",
+      "unit": "kWh"
+    }
+  });
+ *
+ * @example
+ * // Search with optional scope parameter
+ * const result = await search({
+    "location": {
+      "country": "usa"
+    },
+    "activity": {
+      "search": "natural gas",
+      "scope": "1"
+    }
+  });
+ *
+ * @example
+ * // Search with both unit and scope parameters
+ * const result = await search({
+    "location": {
+      "country": "usa",
+      "stateProvince": "california"
+    },
+    "time": {
+      "date": "2025-06-10"
+    },
+    "activity": {
+      "search": "electricity",
+      "unit": "MWh",
+      "scope": "2"
+    },
+    "pagination": {
+      "page": 1,
+      "size": 10
+    }
+  });
  */
 export declare function search(payload: SearchRequest): Promise<TypeRecommenderResponse>;

package/dist/types/index.d.ts

@@ -10,9 +10,12 @@ 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 { 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 +26,4 @@ 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';

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

@@ -135,6 +135,14 @@ 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;
 }
 /**
  * Represents pagination parameters for paginated results.
@@ -150,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/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,5 @@ export interface ActivityRequest {
     activityUnit: string[];
     activityDescription: string;
     confidence: number;
+    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,