emissions-api-sdk 1.0.9 → 1.0.10

package/src/Client.ts

@@ -1,13 +1,14 @@
 import axios from "axios";
 import { ClientConfig } from "./interfaces/Config";
 import { findExpiryTime } from "./utils";
-import { API_DOMAIN, TOKEN_GENERATION_API, CLIENT_SOURCE_EXCEL, CLIENT_SOURCE_SDK } from "./Constants";
+import { API_DOMAIN, TOKEN_GENERATION_API, PAT_TOKEN_EXCHANGE_API, CLIENT_SOURCE_EXCEL, CLIENT_SOURCE_SDK } from "./Constants";
 
 export class Client {
   private static instance: Client | null = null;
 
   private token: string;
   private readonly apiKey: string;
+  private readonly patToken: string;
   private readonly clientId: string;
   private readonly orgId: string;
   private expiresAt: number;
@@ -21,28 +22,30 @@ export class Client {
     config: ClientConfig,
     isUserProvidedToken = false
   ) {
-    const { apiKey="", clientId, orgId="", host, authUrl, isExcelAddIn=false } = config;
+    const { apiKey="", patToken="", clientId, orgId="", host, authUrl, isExcelAddIn=false } = config;
     this.token = token;
     this.clientId = clientId;
     if (isUserProvidedToken) {
       this.apiKey = "";
+      this.patToken = "";
       this.orgId = "";
     } else {
       this.apiKey = apiKey;
+      this.patToken = patToken;
       this.orgId = orgId;
     }
 
     const exp = findExpiryTime(token);
     this.expiresAt = exp;
     this.domain = host ?? API_DOMAIN;
-    this.tokenDomain = authUrl ?? TOKEN_GENERATION_API;
+    this.tokenDomain = authUrl ?? (patToken ? PAT_TOKEN_EXCHANGE_API : TOKEN_GENERATION_API);
     this.isUserProvidedToken = isUserProvidedToken;
     this.clientSource = isExcelAddIn === true ? CLIENT_SOURCE_EXCEL : CLIENT_SOURCE_SDK;
   }
 
 /**
  * Initializes and returns a Client instance with the provided configuration.
- * 
+ *
  * @static
  * @param {ClientConfig} config - The client configuration object
  * @return {Promise<void>} A promise that resolves when the client is initialized
@@ -50,7 +53,8 @@ export class Client {
  *  - custom "host" is provided without "authUrl"
  *  - token is provided without "clientId"
  *  - apiKey is provided without "clientId" or "orgId"
- * 
+ *  - patToken is provided without "clientId" or with "orgId"
+ *
  * @example
  * // Initialize with authentication URL
  * await Client.getClient({
@@ -59,19 +63,25 @@ export class Client {
  *   clientId: 'client123',
  *   orgId: 'org456'
  * });
- * 
+ *
  * // Initialize with existing token
  * await Client.getClient({
  *   token: 'existing-jwt-token',
  *   clientId: 'client123'
  * });
- * 
+ *
  * // Initialize with API key
  * await Client.getClient({
  *   apiKey: 'your-api-key',
  *   clientId: 'client123',
  *   orgId: 'org456'
  * });
+ *
+ * // Initialize with PAT token
+ * await Client.getClient({
+ *   patToken: 'your-personal-access-token',
+ *   clientId: 'client123'
+ * });
  */
 
   public static async getClient(config: ClientConfig): Promise<void> {
@@ -90,14 +100,28 @@ export class Client {
         'If apiKey is provided , "clientId" and "OrgId" must also be provided.'
       );
     }
+    if(config.patToken && !config.clientId){
+      throw new Error(
+        'If patToken is provided, "clientId" must also be provided.'
+      );
+    }
+    if(config.patToken && config.orgId){
+      throw new Error(
+        'orgId should not be provided when using patToken.'
+      );
+    }
     let token: string;
     let isUserProvidedToken = false;
 
     if (config.token && config.clientId) {
       token = config.token;
       isUserProvidedToken = true;
-    } else token = await Client.requestToken(config);
-    Client.instance = new Client(token, config,isUserProvidedToken);
+    } else if (config.patToken && config.clientId) {
+      token = await Client.requestTokenFromPAT(config);
+    } else {
+      token = await Client.requestToken(config);
+    }
+    Client.instance = new Client(token, config, isUserProvidedToken);
   }
 
   /**
@@ -158,12 +182,21 @@ export class Client {
       const now = Math.floor(Date.now() / 1000);
       if (this.expiresAt - now < 60) {
         console.log("[SDK] Refreshing token...");
-        const token = await Client.requestToken({
-          apiKey: this.apiKey,
-          clientId: this.clientId,
-          orgId: this.orgId,
-          authUrl: this.tokenDomain,
-        });
+        let token: string;
+        if (this.patToken) {
+          token = await Client.requestTokenFromPAT({
+            patToken: this.patToken,
+            clientId: this.clientId,
+            authUrl: this.tokenDomain,
+          });
+        } else {
+          token = await Client.requestToken({
+            apiKey: this.apiKey,
+            clientId: this.clientId,
+            orgId: this.orgId,
+            authUrl: this.tokenDomain,
+          });
+        }
         this.token = token;
         this.expiresAt = findExpiryTime(token);
       }
@@ -249,4 +282,35 @@ export class Client {
     if (!res.data) throw new Error("Token response is empty");
     return String(res.data).trim();
   }
+
+  /**
+   * Requests an authentication token by exchanging a Personal Access Token (PAT).
+   *
+   * @private
+   * @static
+   * @param {ClientConfig} config - The client configuration containing PAT and client details
+   * @return {Promise<string>} A promise that resolves to the authentication token string
+   * @throws {Error} Throws an error if the token response is empty
+   *
+   * @example
+   * // Internal usage within the Client class
+   * const token = await Client.requestTokenFromPAT({
+   *   patToken: 'your-personal-access-token',
+   *   clientId: 'client123',
+   *   authUrl: 'https://custom-auth.example.com/exchange'
+   * });
+   */
+  private static async requestTokenFromPAT(config: ClientConfig): Promise<string> {
+    const tokenUrl = config.authUrl ?? PAT_TOKEN_EXCHANGE_API;
+    const res = await axios.post(tokenUrl, null, {
+      headers: {
+        "X-IBM-Client-Id": `saascore-${config.clientId}`,
+        "X-IBM-Envizi-Pat": config.patToken,
+        accept: "application/json",
+      }
+    });
+
+    if (!res.data) throw new Error("Token response is empty");
+    return String(res.data).trim();
+  }
 }

package/src/Constants.ts

@@ -1,5 +1,6 @@
 export const API_DOMAIN = "https://api.ibm.com/ghgemissions/run";
 export const TOKEN_GENERATION_API = "https://api.ibm.com/saascore/run/authentication-retrieve/api-key";
+export const PAT_TOKEN_EXCHANGE_API = "https://api.ibm.com/saascore/run/envizi-auth/exchange";
 export const MOBILE_API_PATH = "/v3/carbon/mobile";
 export const LOCATION_API_PATH = "/v3/carbon/location";
 export const FUGITIVE_API_PATH = "/v3/carbon/fugitive";

package/src/interfaces/Config.ts

@@ -70,6 +70,13 @@ export interface ClientConfig {
    */
   token?: string;
   
+  /**
+   * Optional Personal Access Token (PAT) for authentication.
+   * If provided, it will be exchanged for a JWT token.
+   * Requires clientId to be provided.
+   */
+  patToken?: string;
+  
   /**
    * Optional flag indicating whether the client is running as an Excel Add-In.
    * This may affect certain behaviors like authentication flows.

package/test/client.test.ts

@@ -1,7 +1,7 @@
 import { Client } from "../src/Client";
 import axios from "axios";
 import MockAdapter from "axios-mock-adapter";
-import { TOKEN_GENERATION_API } from "../src/Constants";
+import { TOKEN_GENERATION_API, PAT_TOKEN_EXCHANGE_API } from "../src/Constants";
 import { ClientConfig } from "../src/interfaces/Config";
 
 const mock = new MockAdapter(axios);
@@ -57,6 +57,27 @@ describe("Client initialization and Header Authorization", () => {
       'If apiKey is provided , "clientId" and "OrgId" must also be provided.'
     );
   });
+
+  it("Should throw validation error for missing clientId with patToken", async () => {
+    await expect(
+      Client.getClient({ patToken: "pat-token" } as unknown as ClientConfig)
+    ).rejects.toThrow(
+      'If patToken is provided, "clientId" must also be provided.'
+    );
+  });
+
+  it("Should throw validation error when orgId is provided with patToken", async () => {
+    await expect(
+      Client.getClient({
+        patToken: "pat-token",
+        clientId: "client123",
+        orgId: "org456"
+      } as ClientConfig)
+    ).rejects.toThrow(
+      'orgId should not be provided when using patToken.'
+    );
+  });
+
   it("should not call refresh token if userProvidedToken is set and set token to userProvided", async () => {
     const base64Header = Buffer.from(
       JSON.stringify({ alg: "HS256", typ: "JWT" })
@@ -79,4 +100,75 @@ describe("Client initialization and Header Authorization", () => {
     });
     expect(spy).not.toHaveBeenCalled();
   });
+
+  it("should initialize client with PAT token and return auth header", async () => {
+    const base64Header = Buffer.from(
+      JSON.stringify({ alg: "HS256", typ: "JWT" })
+    ).toString("base64url");
+    const base64Payload = Buffer.from(
+      JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 600 })
+    ).toString("base64url");
+    const mockToken = `${base64Header}.${base64Payload}.Signature`;
+
+    mock.onPost(PAT_TOKEN_EXCHANGE_API).reply(200, mockToken);
+
+    await Client.getClient({
+      patToken: "test-pat-token",
+      clientId: "test-client-id",
+    });
+
+    const instance = Client.getInstance();
+    expect(instance.getAuthHeader()).toEqual({
+      Authorization: `Bearer ${mockToken}`,
+    });
+  });
+
+  it("should initialize client with PAT token and custom authUrl", async () => {
+    const base64Header = Buffer.from(
+      JSON.stringify({ alg: "HS256", typ: "JWT" })
+    ).toString("base64url");
+    const base64Payload = Buffer.from(
+      JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 600 })
+    ).toString("base64url");
+    const mockToken = `${base64Header}.${base64Payload}.Signature`;
+
+    const customAuthUrl = "https://custom-auth.example.com/exchange";
+    mock.onPost(customAuthUrl).reply(200, mockToken);
+
+    await Client.getClient({
+      patToken: "test-pat-token",
+      clientId: "test-client-id",
+      authUrl: customAuthUrl,
+    });
+
+    const instance = Client.getInstance();
+    expect(instance.getAuthHeader()).toEqual({
+      Authorization: `Bearer ${mockToken}`,
+    });
+  });
+
+  it("should call requestTokenFromPAT with correct headers", async () => {
+    const base64Header = Buffer.from(
+      JSON.stringify({ alg: "HS256", typ: "JWT" })
+    ).toString("base64url");
+    const base64Payload = Buffer.from(
+      JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 600 })
+    ).toString("base64url");
+    const mockToken = `${base64Header}.${base64Payload}.Signature`;
+
+    mock.onPost(PAT_TOKEN_EXCHANGE_API).reply((config) => {
+      expect(config.headers?.["X-IBM-Client-Id"]).toBe("saascore-test-client-id");
+      expect(config.headers?.["X-IBM-Envizi-Pat"]).toBe("test-pat-token");
+      expect(config.headers?.["Accept"]).toBe("application/json");
+      return [200, mockToken];
+    });
+
+    await Client.getClient({
+      patToken: "test-pat-token",
+      clientId: "test-client-id",
+    });
+
+    const instance = Client.getInstance();
+    expect(instance).toBeDefined();
+  });
 });

package/test/tokenRefresh.test.ts

@@ -3,7 +3,7 @@ import * as utils from "../src/utils";
 import mockAxios from "axios";
 import MockAdapter from "axios-mock-adapter";
 import { generateMockjwt } from "./testUtils";
-import { TOKEN_GENERATION_API } from "../src/Constants";
+import { TOKEN_GENERATION_API, PAT_TOKEN_EXCHANGE_API } from "../src/Constants";
 
 const mock = new MockAdapter(mockAxios);
 describe("Token refreshing", () => {
@@ -49,4 +49,94 @@ describe("Token refreshing", () => {
     await instance.refreshToken();
     expect(spy).not.toHaveBeenCalledTimes(1);
   });
+
+  it("should refresh PAT token when it is about to expire", async () => {
+    const shortLiveToken = generateMockjwt(1);
+    const refreshedToken = generateMockjwt(600);
+    
+    mock
+      .onPost(PAT_TOKEN_EXCHANGE_API)
+      .replyOnce(200, shortLiveToken)
+      .onPost(PAT_TOKEN_EXCHANGE_API)
+      .replyOnce(200, refreshedToken);
+
+    jest
+      .spyOn(utils, "findExpiryTime")
+      .mockReturnValueOnce(Math.floor(Date.now() / 1000) + 1)
+      .mockReturnValueOnce(Math.floor(Date.now() / 1000) + 600);
+
+    await Client.getClient({
+      patToken: "test-pat-token",
+      clientId: "test-client-id",
+    });
+    const instance = Client.getInstance();
+
+    const spy = jest.spyOn(Client as any, "requestTokenFromPAT");
+
+    await instance.refreshToken();
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith({
+      patToken: "test-pat-token",
+      clientId: "test-client-id",
+      authUrl: PAT_TOKEN_EXCHANGE_API,
+    });
+  });
+
+  it("should not refresh PAT token if it is still valid", async () => {
+    const freshToken = generateMockjwt(600);
+    mock.onPost(PAT_TOKEN_EXCHANGE_API).reply(200, freshToken);
+
+    const spy = jest.spyOn(Client as any, "requestTokenFromPAT");
+
+    jest
+      .spyOn(utils, "findExpiryTime")
+      .mockReturnValue(Math.floor(Date.now() / 1000) + 600);
+
+    await Client.getClient({
+      patToken: "test-pat-token",
+      clientId: "test-client-id",
+    });
+    const instance = Client.getInstance();
+
+    spy.mockClear(); // Clear the initial call from getClient
+
+    await instance.refreshToken();
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("should refresh PAT token with custom authUrl", async () => {
+    const shortLiveToken = generateMockjwt(1);
+    const refreshedToken = generateMockjwt(600);
+    const customAuthUrl = "https://custom-auth.example.com/exchange";
+    
+    mock
+      .onPost(customAuthUrl)
+      .replyOnce(200, shortLiveToken)
+      .onPost(customAuthUrl)
+      .replyOnce(200, refreshedToken);
+
+    const spy = jest.spyOn(Client as any, "requestTokenFromPAT");
+
+    jest
+      .spyOn(utils, "findExpiryTime")
+      .mockReturnValueOnce(Math.floor(Date.now() / 1000) + 1)
+      .mockReturnValueOnce(Math.floor(Date.now() / 1000) + 600);
+
+    await Client.getClient({
+      patToken: "test-pat-token",
+      clientId: "test-client-id",
+      authUrl: customAuthUrl,
+    });
+    const instance = Client.getInstance();
+
+    spy.mockClear(); // Clear the initial call from getClient
+
+    await instance.refreshToken();
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith({
+      patToken: "test-pat-token",
+      clientId: "test-client-id",
+      authUrl: customAuthUrl,
+    });
+  });
 });