emissions-api-sdk 1.0.0

package/src/index.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/src/interfaces/Api.ts

@@ -0,0 +1,300 @@
+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;

package/src/interfaces/Config.ts

@@ -0,0 +1,78 @@
+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/src/interfaces/common.ts

@@ -0,0 +1,174 @@
+/**
+ * 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/src/request.ts

@@ -0,0 +1,50 @@
+import axios, { AxiosRequestConfig } from "axios";
+import { RequestConfig } from "./interfaces/Config";
+import { Client } from "./Client";
+import { CLIENT_SOURCE_HEADER } from "./Constants";
+
+/**
+ * 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 async function makeApiRequest<T>(config: RequestConfig): Promise<T> {
+  const client = Client.getInstance();
+  await client.refreshToken();
+
+  const axiosConfig: AxiosRequestConfig = {
+    method: config.method,
+    url: config.url,
+    data: config.data,
+    params: config.params,
+    headers: {
+      ...client.getAuthHeader(),
+      ...config.headers,
+      'Content-Type': 'application/json',
+      'X-IBM-Client-Id': `ghgemissions-${client.getClientId()}`,
+      [CLIENT_SOURCE_HEADER]: client.getClientSource()
+    },
+  };
+
+  const response = await axios.request<T>(axiosConfig);
+  return response.data;
+}

package/src/utils.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 function findExpiryTime(token: string): any {
+  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;
+}