emissions-api-sdk 1.0.0

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

@@ -0,0 +1,28 @@
+import { CommonRequest } from "../interfaces/Api";
+/**
+ * Performs Scope 1 stationary calculations by making a POST request to the stationary API endpoint.
+ *
+ * @export
+ * @param {CommonRequest} payload - The request data to be sent to the stationary API
+ * @return {Promise<string>} A promise that resolves to the calculation result string returned by the API
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const request = {
+             "time" : {
+                "date": "2025-01-04"
+            },
+            "location": {
+                "country": "usa",
+                                "stateProvince": "new york"
+            },
+            "activity": {
+                            "type":"Coal - Lignite",
+                            "unit": "KJ",
+                            "value": 3
+            },
+            "includeDetails": true
+      };
+ * const result = await calculate(request);
+ */
+export declare function calculate(payload: CommonRequest): Promise<string>;

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

@@ -0,0 +1,27 @@
+import { CalculationRequest } from "../interfaces/Api";
+/**
+ * Performs Scope 2 transportation and distribution emission calculations by making a POST request to the transportation and distribution API endpoint.
+ *
+ * @export
+ * @param {CalculationRequest} payload - The calculation request data for transportation and distribution operations
+ * @return {Promise<string>} A promise that resolves to the calculation result string returned by the API
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const request = {
+             "time" : {
+                "date": "2025-01-04"
+            },
+            "location": {
+                "country": "usa"
+            },
+            "activity": {
+                "type": "Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt",
+                            "unit": ["t","km"],
+                            "value": [1.0,1.0]
+            },
+            "includeDetails": true
+  };
+ * const result = await calculate(request);
+ */
+export declare function calculate(payload: CalculationRequest): Promise<string>;

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

@@ -0,0 +1,27 @@
+import { GenericCalculationRequest } from "../interfaces/Api";
+/**
+ * Performs Scope 2 transportation and distribution emission calculations by making a POST request to the transportation and distribution API endpoint.
+ *
+ * @export
+ * @param {GenericCalculationRequest} payload - The calculation request data for transportation and distribution operations
+ * @return {Promise<string>} A promise that resolves to the calculation result string returned by the API
+ * @throws {Error} May throw an error if the API request fails
+ *
+ * @example
+ * const request = {
+             "time" : {
+                "date": "2025-01-04"
+            },
+            "location": {
+                "country": "usa"
+            },
+            "activity": {
+                "type": "Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt",
+                            "unit": ["t","km"],
+                            "value": [1.0,1.0]
+            },
+            "includeDetails": true
+  };
+ * const result = await calculate(request);
+ */
+export declare function calculate(payload: GenericCalculationRequest): Promise<string>;

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+export { Client } from './Client';
+export * as Location from './api/Location';
+export * as Fugitive from './api/Fugitive';
+export * as Mobile from './api/Mobile';
+export * as Stationary from './api/Stationary';
+export * as Calculation from './api/Calculation';
+export * as TransportationAndDistribution from './api/TransportationAndDistribution';
+export * as Factor from './api/Factor';
+export * as FactorSets from './api/FactorSets';
+export { ClientConfig } from './interfaces/Config';

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

@@ -0,0 +1,286 @@
+import { Activity, Location, Time, CombinedUnitsActivity, FactorActivity, SearchActivity, Pagination, FactorActivityWithFactorId, CombinedUnitsActivityWithFactorId, ActivityWithFactorId } 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
+ * while keeping the 'value' property required.
+ *
+ * @typedef {Object} LocationActivity
+ * @property {any} value - The required activity value (e.g., quantity, amount, or measurement)
+ * @property {string} [type] - Optional activity type identifier
+ * @property {string} [unit] - Optional unit of measurement for the activity value
+ *
+ * @example
+ * // Minimal valid LocationActivity with only required properties
+ * const minimalActivity: LocationActivity = {
+ *   value: 100
+ * };
+ *
+ * // Complete LocationActivity with all properties
+ * const fullActivity: LocationActivity = {
+ *   value: 100,
+ *   type: 'electricity',
+ *   unit: 'kWh'
+ * };
+ */
+type LocationActivity = Partial<Pick<Activity, 'type' | 'unit'>> & Pick<Activity, 'value'>;
+/**
+ * Represents activity data associated with a location that includes a specific factor ID.
+ * Extends the Activity concept by requiring a factorId while making only the value property
+ * required and the unit property optional.
+ *
+ * @typedef {Object} LocationActivityWithFactorId
+ * @property {number} factorId - The unique identifier for the emission factor to be used
+ * @property {any} value - The required activity value (e.g., quantity, amount, or measurement)
+ * @property {string} [unit] - Optional unit of measurement for the activity value
+ *
+ * @example
+ * // Minimal valid LocationActivityWithFactorId with only required properties
+ * const minimalActivity: LocationActivityWithFactorId = {
+ *   factorId: 12345,
+ *   value: 100
+ * };
+ *
+ * // Complete LocationActivityWithFactorId with all properties
+ * const fullActivity: LocationActivityWithFactorId = {
+ *   factorId: 12345,
+ *   value: 100,
+ *   unit: 'kWh'
+ * };
+ */
+type LocationActivityWithFactorId = {
+    factorId: number;
+} & Partial<Pick<Activity, 'unit'>> & Pick<Activity, 'value'>;
+/**
+ * Request parameters for location-based calculations without specifying a factor ID.
+ * Used for calculating emissions or other metrics based on location data.
+ *
+ * @interface LocationRequestWithoutFactorId
+ */
+export interface LocationRequestWithoutFactorId {
+    /**
+     * The geographical location information.
+     * Contains coordinates and possibly other location-specific data.
+     */
+    location: Location;
+    /**
+     * Optional time(YYYY-MM-DD)information for the location data.
+     * Can be used to specify when the activity occurred.
+     */
+    time?: Time;
+    /**
+     * The activity associated with this location.
+     * Defines what type of action or event occurred at the location.
+     */
+    activity: LocationActivity;
+    /**
+     * Whether to include additional details in the response.
+     * When true, the API will return more comprehensive information.
+     * @default false
+     */
+    includeDetails?: boolean;
+}
+/**
+ * Request parameters for location-based calculations with a specific factor ID.
+ * Used when the emission factor is already known and doesn't need to be determined by location.
+ *
+ * @interface LocationRequestWithFactorId
+ */
+export interface LocationRequestWithFactorId {
+    /**
+     * The activity associated with this location, including the specific factor ID to use.
+     */
+    activity: LocationActivityWithFactorId;
+    /**
+     * 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 without specifying a factor ID.
+ * Used for general-purpose calculations based on location, time, and activity data.
+ *
+ * @interface CommonRequestWithoutFactorId
+ */
+export interface CommonRequestWithoutFactorId {
+    /**
+     * The geographical location information.
+     * Contains coordinates and possibly other location-specific data.
+     */
+    location: Location;
+    /**
+     * Optional time information for the activity data.
+     * Can be used to specify when the activity occurred.
+     */
+    time?: Time;
+    /**
+     * The activity data for the calculation.
+     * Contains complete activity information including type, value, and unit.
+     */
+    activity: Activity;
+    /**
+     * 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 {
+    /**
+     * The activity data for the calculation, including the specific factor ID to use.
+     */
+    activity: ActivityWithFactorId;
+    /**
+     * 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.
+ * Used for calculations that may involve multiple units or complex activity data.
+ *
+ * @interface GenericCalculationRequestWithoutFactorId
+ */
+export interface GenericCalculationRequestWithoutFactorId {
+    /**
+     * The geographical location information.
+     * Contains coordinates and possibly other location-specific data.
+     */
+    location: Location;
+    /**
+     * Optional time information for the activity data.
+     * Can be used to specify when the activity occurred.
+     */
+    time?: Time;
+    /**
+     * The combined units activity data for the calculation.
+     * Supports complex activities with multiple units or components.
+     */
+    activity: CombinedUnitsActivity;
+    /**
+     * 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 with a specific factor ID.
+ * Used for complex calculations where the emission factor is already known.
+ *
+ * @interface GenericCalculationRequestWithFactorId
+ */
+export interface GenericCalculationRequestWithFactorId {
+    /**
+     * The combined units activity data for the calculation, including the specific factor ID to use.
+     * Supports complex activities with multiple units or components.
+     */
+    activity: CombinedUnitsActivityWithFactorId;
+    /**
+     * Whether to include additional details in the response.
+     * When true, the API will return more comprehensive information.
+     * @default false
+     */
+    includeDetails?: boolean;
+}
+/**
+ * Request parameters for retrieving factor information without specifying a factor ID.
+ * Used to look up appropriate emission factors based on location, time, and activity type.
+ *
+ * @interface FactorRequestWithoutFactorId
+ */
+export interface FactorRequestWithoutFactorId {
+    /**
+     * The geographical location information.
+     * Used to determine which factors are applicable for the region.
+     */
+    location: Location;
+    /**
+     * Optional time information for the factor lookup.
+     * Can be used to find factors applicable at a specific point in time.
+     */
+    time?: Time;
+    /**
+     * The activity information used to determine which factors to retrieve.
+     * Typically includes the activity type and possibly unit information.
+     */
+    activity: FactorActivity;
+}
+/**
+ * Request parameters for retrieving specific factor information by ID.
+ * Used when the exact factor to retrieve is already known.
+ *
+ * @interface FactorRequestWithFactorId
+ */
+export interface FactorRequestWithFactorId {
+    /**
+     * The activity information including the specific factor ID to retrieve.
+     */
+    activity: FactorActivityWithFactorId;
+}
+/**
+ * Request parameters for searching factors or activities.
+ * Used to find relevant factors or activities based on location, time, and search criteria.
+ *
+ * @interface SearchRequest
+ */
+export interface SearchRequest {
+    /**
+     * The geographical location information to scope the search.
+     * Used to find factors or activities relevant to a specific region.
+     */
+    location: Location;
+    /**
+     * Optional time information to scope the search.
+     * Can be used to find factors or activities relevant at a specific point in time.
+     */
+    time?: Time;
+    /**
+     * The search criteria and parameters.
+     * Contains information about what to search for and any filters to apply.
+     */
+    activity: SearchActivity;
+    /**
+     * Optional pagination parameters for the search results.
+     * Used to limit the number of results and implement paging.
+     */
+    pagination?: Pagination;
+}
+/**
+ * Union type representing either a factor request with or without a specific factor ID.
+ * Allows the API to handle both types of requests with a single parameter type.
+ *
+ * @typedef {FactorRequestWithoutFactorId | FactorRequestWithFactorId} FactorRequest
+ */
+export type FactorRequest = FactorRequestWithoutFactorId | FactorRequestWithFactorId;
+/**
+ * Union type representing either a generic calculation request with or without a specific factor ID.
+ * Allows the API to handle both types of calculation requests with a single parameter type.
+ *
+ * @typedef {GenericCalculationRequestWithoutFactorId | GenericCalculationRequestWithFactorId} CalculationRequest
+ */
+export type CalculationRequest = GenericCalculationRequestWithoutFactorId | GenericCalculationRequestWithFactorId;
+/**
+ * Union type representing either a common request with or without a specific factor ID.
+ * Allows the API to handle both types of common requests with a single parameter type.
+ *
+ * @typedef {CommonRequestWithoutFactorId | CommonRequestWithFactorId} CommonRequest
+ */
+export type CommonRequest = CommonRequestWithoutFactorId | CommonRequestWithFactorId;
+/**
+ * Union type representing either a location request with or without a specific factor ID.
+ * Allows the API to handle both types of location requests with a single parameter type.
+ *
+ * @typedef {LocationRequestWithoutFactorId | LocationRequestWithFactorId} LocationRequest
+ */
+export type LocationRequest = LocationRequestWithoutFactorId | LocationRequestWithFactorId;
+export {};

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

@@ -0,0 +1,66 @@
+import { Method } from "axios";
+/**
+ * Configuration for making HTTP requests.
+ * @interface RequestConfig
+ */
+export interface RequestConfig {
+    /**
+     * The HTTP method to use for the request (GET, POST, PUT, DELETE, etc.).
+     */
+    method: Method;
+    /**
+     * The URL to which the request will be sent.
+     */
+    url: string;
+    /**
+     * Optional request body data to be sent with the request.
+     */
+    data?: any;
+    /**
+     * Optional URL query parameters to be appended to the request URL.
+     */
+    params?: any;
+    /**
+     * Optional HTTP headers to be included with the request.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Configuration for initializing a client instance.
+ * @interface ClientConfig
+ */
+export interface ClientConfig {
+    /**
+     * Optional API key used for authentication.
+     */
+    apiKey?: string;
+    /**
+     * Unique identifier for the client application.
+     * This is required for all client instances.
+     */
+    clientId: string;
+    /**
+     * Optional organization identifier.
+     */
+    orgId?: string;
+    /**
+     * Optional host URL for API requests.
+     * If not provided, a default host will be used.
+     */
+    host?: string;
+    /**
+     * Optional authentication URL.
+     * If not provided, a default authentication endpoint will be used.
+     */
+    authUrl?: string;
+    /**
+     * Optional authentication token.
+     * If provided, it will be used instead of requesting a new token.
+     */
+    token?: string;
+    /**
+     * Optional flag indicating whether the client is running as an Excel Add-In.
+     * This may affect certain behaviors like authentication flows.
+     */
+    isExcelAddIn?: boolean;
+}

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

@@ -0,0 +1,152 @@
+/**
+ * Represents a geographical location.
+ * @interface Location
+ */
+export interface Location {
+    /**
+     * The country of the location.
+     */
+    country: string;
+    /**
+     * Optional state or province within the country.
+     */
+    stateProvince?: string;
+    /**
+     * Optional power grid identifier for the location.
+     */
+    powerGrid?: string;
+}
+/**
+ * Represents a point in time with date information.
+ * @interface Time
+ */
+export interface Time {
+    /**
+     * The date in string format.
+     */
+    date: string;
+}
+/**
+ * Represents an activity with type, value, and unit of measurement.
+ * @interface Activity
+ */
+export interface Activity {
+    /**
+     * The type or category of the activity.
+     */
+    type: string;
+    /**
+     * The numerical value of the activity.
+     */
+    value: number;
+    /**
+     * The unit of measurement for the activity value.
+     */
+    unit: string;
+}
+/**
+ * Represents an activity identified by a factor ID instead of a type.
+ * @interface ActivityWithFactorId
+ */
+export interface ActivityWithFactorId {
+    /**
+     * The unique identifier for the activity factor.
+     */
+    factorId: number;
+    /**
+     * The numerical value of the activity.
+     */
+    value: number;
+    /**
+     * The unit of measurement for the activity value.
+     */
+    unit: string;
+}
+/**
+ * Represents an activity that can have single or multiple values and units.
+ * @interface CombinedUnitsActivity
+ */
+export interface CombinedUnitsActivity {
+    /**
+     * The type or category of the activity.
+     */
+    type: string;
+    /**
+     * The numerical value(s) of the activity. Can be a single number or an array of numbers.
+     */
+    value: number | number[];
+    /**
+     * The unit(s) of measurement for the activity value(s). Can be a single string or an array of strings.
+     */
+    unit: string | string[];
+}
+/**
+ * Represents an activity with factor ID that can have single or multiple values and units.
+ * @interface CombinedUnitsActivityWithFactorId
+ */
+export interface CombinedUnitsActivityWithFactorId {
+    /**
+     * The unique identifier for the activity factor.
+     */
+    factorId: number;
+    /**
+     * The numerical value(s) of the activity. Can be a single number or an array of numbers.
+     */
+    value: number | number[];
+    /**
+     * The unit(s) of measurement for the activity value(s). Can be a single string or an array of strings.
+     */
+    unit: string | string[];
+}
+/**
+ * Represents a factor activity with a type and optional unit.
+ * @interface FactorActivity
+ */
+export interface FactorActivity {
+    /**
+     * The type or category of the factor activity.
+     */
+    type: string;
+    /**
+     * Optional unit of measurement for the factor activity.
+     */
+    unit?: string;
+}
+/**
+ * Represents a factor activity identified by a factor ID instead of a type.
+ * @interface FactorActivityWithFactorId
+ */
+export interface FactorActivityWithFactorId {
+    /**
+     * The unique identifier for the factor activity.
+     */
+    factorId: number;
+    /**
+     * Optional unit of measurement for the factor activity.
+     */
+    unit?: string;
+}
+/**
+ * Represents a search query for activities.
+ * @interface SearchActivity
+ */
+export interface SearchActivity {
+    /**
+     * The search query string.
+     */
+    search: string;
+}
+/**
+ * Represents pagination parameters for paginated results.
+ * @interface Pagination
+ */
+export interface Pagination {
+    /**
+     * The page number (1-based).
+     */
+    page: number;
+    /**
+     * The number of items per page.
+     */
+    size: number;
+}

package/dist/types/request.d.ts

@@ -0,0 +1,25 @@
+import { RequestConfig } from "./interfaces/Config";
+/**
+ * Makes an API request with standardized headers and token refresh.
+ *
+ * @export
+ * @template T The expected response data type
+ * @param {RequestConfig} config - The request configuration including method, URL, data, params, and optional headers
+ * @return {Promise<T>} A promise that resolves to the response data of type T
+ * @throws {Error} May throw an error if the API request fails or token refresh fails
+ *
+ * @example
+ * interface UserData {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const userData = await makeApiRequest<UserData>({
+ *   method: 'GET',
+ *   url: 'https://api.example.com/users/123',
+ *   headers: { 'X-Custom-Header': 'value' }
+ * });
+ * console.log(userData.name); // Typed access to the response data
+ */
+export declare function makeApiRequest<T>(config: RequestConfig): Promise<T>;

package/dist/types/utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Extracts the expiration time from a JWT token and give the token expiry time.
+ *
+ * @export
+ * @param {string} token - The JWT token to extract the expiration time from
+ * @return {any} The expiration time value from the token's payload
+ * @throws {Error} Throws an error if the exp field is missing in the token
+ *
+ * @example
+ * const jwtToken = 'your-token';
+ * const expiryTime = findExpiryTime(jwtToken);
+ * console.log(new Date(expiryTime * 1000).toISOString()); // Convert to date if it's a Unix timestamp
+ */
+export declare function findExpiryTime(token: string): any;

package/dist/utils.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findExpiryTime = findExpiryTime;
+/**
+ * Extracts the expiration time from a JWT token and give the token expiry time.
+ *
+ * @export
+ * @param {string} token - The JWT token to extract the expiration time from
+ * @return {any} The expiration time value from the token's payload
+ * @throws {Error} Throws an error if the exp field is missing in the token
+ *
+ * @example
+ * const jwtToken = 'your-token';
+ * const expiryTime = findExpiryTime(jwtToken);
+ * console.log(new Date(expiryTime * 1000).toISOString()); // Convert to date if it's a Unix timestamp
+ */
+function findExpiryTime(token) {
+    const payload = token.split('.')[1];
+    const decoded = JSON.parse(Buffer.from(payload, 'base64').toString('utf8'));
+    if (!decoded.exp)
+        throw new Error('exp field is missing in the token');
+    return decoded.exp;
+}

package/jest.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['test'],
+  testMatch: ['**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json', 'node'],
+  collectCoverage: true,
+  coverageDirectory: 'dist/coverage'
+};