@codex-data/sdk 1.0.9 → 1.0.10

package/src/sdk/index.test.ts

@@ -1,6 +1,6 @@
 import { DocumentNode } from "graphql";
 
-import { Codex } from "./index";
+import { ApiConfig, Codex } from "./index";
 
 const getNetworksDocument = {
   kind: "Document",
@@ -34,45 +34,396 @@ const subscribePriceUpdatedString = `subscription onPriceUpdated($address: Strin
 
 describe("Codex", () => {
   let sdk: Codex;
+
   beforeEach(() => {
     sdk = new Codex("dummy-key");
   });
 
+  describe("constructor", () => {
+    it("should initialize with default config when no apiConfig provided", () => {
+      const sdkInstance = new Codex("test-key");
+      expect(sdkInstance).toBeInstanceOf(Codex);
+      expect(sdkInstance.queries).toBeDefined();
+      expect(sdkInstance.mutations).toBeDefined();
+      expect(sdkInstance.subscriptions).toBeDefined();
+    });
+
+    it("should throw error when apiKey is not provided", () => {
+      expect(() => new Codex("")).toThrow("apiKey must be defined");
+      expect(() => new Codex(null as any)).toThrow("apiKey must be defined");
+      expect(() => new Codex(undefined as any)).toThrow(
+        "apiKey must be defined",
+      );
+    });
+
+    it("should initialize with custom apiConfig", () => {
+      const customConfig: Partial<ApiConfig> = {
+        apiUrl: "https://custom.api.com/graphql",
+        apiRealtimeUrl: "wss://custom.api.com/graphql",
+        headers: { "Custom-Header": "value" },
+        wsHeaders: { "WS-Header": "ws-value" },
+        ws: false,
+      };
+
+      const sdkInstance = new Codex("test-key", customConfig);
+      expect(sdkInstance).toBeInstanceOf(Codex);
+    });
+
+    it("should merge custom config with default config", () => {
+      const customConfig: Partial<ApiConfig> = {
+        headers: { "Custom-Header": "value" },
+        ws: false,
+      };
+
+      // Mock the createGraphQLClient and createWebsocketClient to verify they're called with merged config
+      const createGraphQLClientSpy = jest.spyOn(
+        Codex.prototype as any,
+        "createGraphQLClient",
+      );
+      const createWebsocketClientSpy = jest.spyOn(
+        Codex.prototype as any,
+        "createWebsocketClient",
+      );
+
+      new Codex("test-key", customConfig);
+
+      // Verify the merged config was used
+      expect(createGraphQLClientSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          apiUrl: "https://graph.codex.io/graphql", // default
+          apiRealtimeUrl: "wss://graph.codex.io/graphql", // default
+          headers: { "Custom-Header": "value" }, // custom
+          ws: false, // custom
+        }),
+      );
+
+      createGraphQLClientSpy.mockRestore();
+      createWebsocketClientSpy.mockRestore();
+    });
+  });
+
+  describe("updateConfig", () => {
+    it("should update configuration and recreate clients", () => {
+      const disposeSpy = jest.spyOn(sdk, "dispose");
+      const createGraphQLClientSpy = jest.spyOn(
+        sdk as any,
+        "createGraphQLClient",
+      );
+      const createWebsocketClientSpy = jest.spyOn(
+        sdk as any,
+        "createWebsocketClient",
+      );
+
+      const newConfig: Partial<ApiConfig> = {
+        apiUrl: "https://new-api.com/graphql",
+        headers: { "New-Header": "new-value" },
+      };
+
+      sdk.updateConfig(newConfig);
+
+      expect(disposeSpy).toHaveBeenCalled();
+      expect(createGraphQLClientSpy).toHaveBeenCalled();
+      expect(createWebsocketClientSpy).toHaveBeenCalled();
+
+      disposeSpy.mockRestore();
+      createGraphQLClientSpy.mockRestore();
+      createWebsocketClientSpy.mockRestore();
+    });
+
+    it("should merge new config with existing config", () => {
+      const initialConfig: Partial<ApiConfig> = {
+        headers: { "Initial-Header": "initial-value" },
+        ws: true,
+      };
+
+      const sdkWithConfig = new Codex("test-key", initialConfig);
+      const parseConfigSpy = jest.spyOn(sdkWithConfig as any, "parseConfig");
+
+      const updateConfig: Partial<ApiConfig> = {
+        headers: { "Updated-Header": "updated-value" },
+        apiUrl: "https://updated-api.com/graphql",
+      };
+
+      sdkWithConfig.updateConfig(updateConfig);
+
+      // Verify parseConfig was called with merged configuration
+      expect(parseConfigSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          headers: { "Updated-Header": "updated-value" },
+          apiUrl: "https://updated-api.com/graphql",
+          ws: true, // from initial config
+        }),
+      );
+
+      parseConfigSpy.mockRestore();
+    });
+
+    it("should dispose existing websocket connection before creating new one", () => {
+      // Mock wsClient
+      const mockDispose = jest.fn();
+      (sdk as any).wsClient = { dispose: mockDispose };
+
+      const disposeSpy = jest.spyOn(sdk, "dispose");
+
+      sdk.updateConfig({ headers: { "New-Header": "value" } });
+
+      expect(disposeSpy).toHaveBeenCalled();
+      disposeSpy.mockRestore();
+    });
+  });
+
+  describe("getRequestHeaders", () => {
+    it("should return static headers when no dynamic headers are configured", async () => {
+      const staticHeaders = { "Static-Header": "static-value" };
+      const sdkWithHeaders = new Codex("test-key", { headers: staticHeaders });
+
+      const headers = await (sdkWithHeaders as any).getRequestHeaders();
+
+      expect(headers).toEqual(staticHeaders);
+    });
+
+    it("should return dynamic headers when applyHeaders is configured", async () => {
+      const dynamicHeaders = { "Dynamic-Header": "dynamic-value" };
+      const applyHeaders = jest.fn().mockResolvedValue(dynamicHeaders);
+
+      const sdkWithDynamicHeaders = new Codex("test-key", { applyHeaders });
+
+      const headers = await (sdkWithDynamicHeaders as any).getRequestHeaders();
+
+      expect(applyHeaders).toHaveBeenCalled();
+      expect(headers).toEqual(dynamicHeaders);
+    });
+
+    it("should merge static and dynamic headers with dynamic taking precedence", async () => {
+      const staticHeaders = { "Header-1": "static", "Header-2": "static" };
+      const dynamicHeaders = { "Header-2": "dynamic", "Header-3": "dynamic" };
+      const applyHeaders = jest.fn().mockResolvedValue(dynamicHeaders);
+
+      const sdkWithBothHeaders = new Codex("test-key", {
+        headers: staticHeaders,
+        applyHeaders,
+      });
+
+      const headers = await (sdkWithBothHeaders as any).getRequestHeaders();
+
+      expect(headers).toEqual({
+        "Header-1": "static",
+        "Header-2": "dynamic", // dynamic overrides static
+        "Header-3": "dynamic",
+      });
+    });
+
+    it("should handle applyHeaders returning undefined", async () => {
+      const staticHeaders = { "Static-Header": "static-value" };
+      const applyHeaders = jest.fn().mockResolvedValue(undefined);
+
+      const sdkWithUndefinedDynamic = new Codex("test-key", {
+        headers: staticHeaders,
+        applyHeaders,
+      });
+
+      const headers = await (
+        sdkWithUndefinedDynamic as any
+      ).getRequestHeaders();
+
+      expect(headers).toEqual(staticHeaders);
+    });
+  });
+
+  describe("dispose", () => {
+    it("should dispose websocket client when it exists", async () => {
+      const mockDispose = jest.fn();
+      (sdk as any).wsClient = { dispose: mockDispose };
+
+      await sdk.dispose();
+
+      expect(mockDispose).toHaveBeenCalled();
+    });
+
+    it("should not throw error when websocket client is undefined", async () => {
+      (sdk as any).wsClient = undefined;
+
+      await expect(sdk.dispose()).resolves.not.toThrow();
+    });
+  });
+
+  describe("websocket configuration", () => {
+    it("should create websocket client when ws is true (default)", () => {
+      const createWebsocketClientSpy = jest.spyOn(
+        Codex.prototype as any,
+        "createWebsocketClient",
+      );
+
+      new Codex("test-key");
+
+      expect(createWebsocketClientSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ ws: true }),
+      );
+
+      createWebsocketClientSpy.mockRestore();
+    });
+
+    it("should not create websocket client when ws is false", () => {
+      const createWebsocketClientSpy = jest.spyOn(
+        Codex.prototype as any,
+        "createWebsocketClient",
+      );
+
+      new Codex("test-key", { ws: false });
+
+      expect(createWebsocketClientSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ ws: false }),
+      );
+
+      createWebsocketClientSpy.mockRestore();
+    });
+
+    it("should throw error when trying to subscribe without websocket enabled", () => {
+      const sdkWithoutWs = new Codex("test-key", { ws: false });
+
+      expect(() => {
+        sdkWithoutWs.subscribe(
+          subscribePriceUpdatedString,
+          { address: "0xtoken", networkId: 1 },
+          { next: jest.fn(), error: jest.fn(), complete: jest.fn() },
+        );
+      }).toThrow("Websocket is not enabled in the config");
+    });
+  });
+
   describe("query", () => {
-    it("send a fetch request with the correct params", async () => {
+    it("should send a fetch request with the correct params", async () => {
       const fetchSpy = jest
         .spyOn(sdk["client"], "request")
         .mockResolvedValue({} as unknown);
+
       await sdk.query(getNetworksDocument, {});
+
       expect(fetchSpy).toHaveBeenCalledWith(getNetworksDocument, {}, {});
     });
+
+    it("should include request headers in the request", async () => {
+      const mockHeaders = { "Test-Header": "test-value" };
+      const getRequestHeadersSpy = jest
+        .spyOn(sdk as any, "getRequestHeaders")
+        .mockResolvedValue(mockHeaders);
+      const fetchSpy = jest
+        .spyOn(sdk["client"], "request")
+        .mockResolvedValue({} as unknown);
+
+      await sdk.query(getNetworksDocument, {});
+
+      expect(getRequestHeadersSpy).toHaveBeenCalled();
+      expect(fetchSpy).toHaveBeenCalledWith(
+        getNetworksDocument,
+        {},
+        mockHeaders,
+      );
+
+      getRequestHeadersSpy.mockRestore();
+    });
   });
+
+  describe("mutation", () => {
+    it("should send a request with the correct params", async () => {
+      const fetchSpy = jest
+        .spyOn(sdk["client"], "request")
+        .mockResolvedValue({} as unknown);
+
+      await sdk.mutation(getNetworksDocument, {});
+
+      expect(fetchSpy).toHaveBeenCalledWith(getNetworksDocument, {}, {});
+    });
+
+    it("should include request headers in the request", async () => {
+      const mockHeaders = { "Test-Header": "test-value" };
+      const getRequestHeadersSpy = jest
+        .spyOn(sdk as any, "getRequestHeaders")
+        .mockResolvedValue(mockHeaders);
+      const fetchSpy = jest
+        .spyOn(sdk["client"], "request")
+        .mockResolvedValue({} as unknown);
+
+      await sdk.mutation(getNetworksDocument, {});
+
+      expect(getRequestHeadersSpy).toHaveBeenCalled();
+      expect(fetchSpy).toHaveBeenCalledWith(
+        getNetworksDocument,
+        {},
+        mockHeaders,
+      );
+
+      getRequestHeadersSpy.mockRestore();
+    });
+  });
+
   describe("send", () => {
     it("should return the results of the query", async () => {
       const fetchSpy = jest
         .spyOn(sdk["client"], "request")
         .mockResolvedValue({} as unknown);
+
       await sdk.send(getNetworksString, {});
+
       expect(fetchSpy).toHaveBeenCalledWith(getNetworksString, {}, {});
     });
+
+    it("should include request headers in the request", async () => {
+      const mockHeaders = { "Test-Header": "test-value" };
+      const getRequestHeadersSpy = jest
+        .spyOn(sdk as any, "getRequestHeaders")
+        .mockResolvedValue(mockHeaders);
+      const fetchSpy = jest
+        .spyOn(sdk["client"], "request")
+        .mockResolvedValue({} as unknown);
+
+      await sdk.send(getNetworksString, {});
+
+      expect(getRequestHeadersSpy).toHaveBeenCalled();
+      expect(fetchSpy).toHaveBeenCalledWith(getNetworksString, {}, mockHeaders);
+
+      getRequestHeadersSpy.mockRestore();
+    });
   });
+
   describe("subscribe", () => {
     it("should return a cleanup function", () => {
-      const next = jest.fn(),
-        error = jest.fn(),
-        complete = jest.fn();
-      const sink = {
-        next,
-        error,
-        complete,
-      };
+      const next = jest.fn();
+      const error = jest.fn();
+      const complete = jest.fn();
+      const sink = { next, error, complete };
+
       jest.spyOn(sdk["wsClient"] as any, "subscribe").mockReturnValue(() => {});
+
       const cleanup = sdk.subscribe(
         subscribePriceUpdatedString,
         { address: "0xtoken", networkId: 1 },
         sink,
       );
+
       expect(typeof cleanup).toBe("function");
     });
+
+    it("should call wsClient.subscribe with correct parameters", () => {
+      const next = jest.fn();
+      const error = jest.fn();
+      const complete = jest.fn();
+      const sink = { next, error, complete };
+      const variables = { address: "0xtoken", networkId: 1 };
+
+      const subscribeSpy = jest
+        .spyOn(sdk["wsClient"] as any, "subscribe")
+        .mockReturnValue(() => {});
+
+      sdk.subscribe(subscribePriceUpdatedString, variables, sink);
+
+      expect(subscribeSpy).toHaveBeenCalledWith(
+        {
+          query: subscribePriceUpdatedString,
+          variables,
+        },
+        sink,
+      );
+    });
   });
 });

package/src/sdk/index.ts

@@ -48,17 +48,34 @@ export class Codex {
   public mutations: Mutation;
   public subscriptions: Subscribe;
 
+  /**
+   * @param apiKey - The api key to use for the requests.
+   * @param apiConfig - The configuration to use for the requests.
+   */
   constructor(
     private apiKey: string,
     private apiConfig?: Partial<ApiConfig>,
   ) {
-    invariant(this.apiKey, "apiKey must be defined");
-    const config = Object.assign({}, defaultConfig, apiConfig);
-
+    const config = this.parseConfig(this.apiConfig ?? {});
     this.queries = new Query(this);
     this.mutations = new Mutation(this);
     this.subscriptions = new Subscribe(this);
-    this.client = new GraphQLClient(config.apiUrl, {
+
+    this.client = this.createGraphQLClient(config);
+    this.wsClient = this.createWebsocketClient(config);
+
+    this.wsClient?.on("error", (error) => {
+      console.error("Websocket error: ", error);
+    });
+  }
+
+  private parseConfig(config: Partial<ApiConfig>) {
+    invariant(this.apiKey, "apiKey must be defined");
+    return Object.assign({}, defaultConfig, config);
+  }
+
+  private createGraphQLClient(config: ApiConfig) {
+    return new GraphQLClient(config.apiUrl, {
       method: "POST",
       headers: new Headers({
         "Content-Type": "application/json",
@@ -67,7 +84,10 @@ export class Codex {
         ...config.headers,
       }),
     });
-    this.wsClient = config.ws
+  }
+
+  private createWebsocketClient(config: ApiConfig) {
+    return config.ws
       ? createClient({
           webSocketImpl: WebSocket,
           keepAlive: 10_000, // ping server every 10 seconds
@@ -91,6 +111,51 @@ export class Codex {
     return headers;
   }
 
+  /**
+   * Need to update the headers on the websocket connection.
+   * This is useful if the api key changes, or you need to modify the connection init params at all.
+   * NOTE: it will dispose of the old connection, so all existing subscriptions will be closed.
+   */
+  public updateConfig(incomingConfig: Partial<ApiConfig>) {
+    // If we have an existing websocket connection, dispose of it.
+    if (this.wsClient) this.dispose();
+
+    // Merge the incoming config with the existing config.
+    const config = this.parseConfig(
+      Object.assign({}, this.apiConfig, incomingConfig),
+    );
+
+    // Create a new websocket connection with the new headers.
+    this.wsClient = this.createWebsocketClient(config);
+    this.client = this.createGraphQLClient(config);
+
+    this.wsClient?.on("error", (error) => {
+      console.error("Websocket error: ", error);
+    });
+    this.wsClient?.on("closed", (er) => {
+      console.log("Websocket closed", er);
+    });
+    this.wsClient?.on("connecting", () => {
+      console.log("Websocket connecting");
+    });
+  }
+
+  /**
+   * Call this to dispose of the websocket connection, and make this class ready for garbage collection.
+   * This will also close any open subscriptions.
+   *
+   * It's useful for when you need to modify some of the configuration, or when you're done with the class.
+   */
+  public async dispose() {
+    this.wsClient?.dispose();
+  }
+
+  /**
+   * This is the preferred way to execute queries.
+   * @param doc - The graphql document node to execute.
+   * @param args - The variables to pass to the document.
+   * @returns The result of the query.
+   */
   public async query<TResults, TVars extends Variables>(
     doc: TypedDocumentNode<TResults, TVars>,
     args: TVars = {} as TVars,
@@ -103,6 +168,12 @@ export class Codex {
     return res as TResults;
   }
 
+  /**
+   * This is functionally the same thing as the `query` method, but it's more expressive.
+   * @param doc - The graphql document node to execute.
+   * @param args - The variables to pass to the document.
+   * @returns The result of the mutation.
+   */
   public async mutation<TResults, TVars extends Variables>(
     doc: TypedDocumentNode<TResults, TVars>,
     args: TVars = {} as TVars,
@@ -115,7 +186,13 @@ export class Codex {
     return res as TResults;
   }
 
-  // Very simple network based fetch implementation, no compilation required
+  /**
+   * This should be used when you don't want to use graphql libaries to create a document node,
+   * and would rather just pass in a string.
+   * @param gqlString - The graphql document string to execute.
+   * @param args - The variables to pass to the document.
+   * @returns The result of the mutation.
+   */
   public async send<TResults, V extends Variables = Variables>(
     gqlString: string,
     args: V = {} as V,
@@ -128,6 +205,12 @@ export class Codex {
     return res;
   }
 
+  /**
+   * @param doc - The graphql document string to execute.
+   * @param args - The variables to pass to the document.
+   * @param sink - The sink to receive the results.
+   * @returns A cleanup function to unsubscribe from the subscription.
+   */
   public subscribe<
     TResults,
     TVars extends Record<string, unknown> = Record<string, never>,