feat: Add support for setting additional headers and strictApi

doc/api_reference/session.rst

@@ -23,6 +23,8 @@ Construct Session instance with API credentials.
     :param Array [options.serverInformationValues=[]]: Optional list of server information values to retrieve.
     :param Object [options.eventHubOptions={}]: Options to configure event hub with.
     :param string [options.clientToken=null]: Client identifier included in update events caused by operations performed by this session.
+    :param Object [options.headers]: Additional headers to send with the request
+    :param Object [options.strictApi]: Turn on strict API mode
 
 Function ``call``
 =================
@@ -45,8 +47,12 @@ ServerError
 
 
     :param Array operations: API operations.
+    :param Object [options]: options
+    :param Object [options.abortController]: - Deprecated in favour of options.signal
+    :param Object [options.signal]: - Abort signal user for aborting requests prematurely
+    :param Object [options.headers]: - Additional headers to send with the request
 
-
+    :return Promise: Promise which will be resolved with an array of decoded responses.
 
 Function ``getSchema``
 ======================

source/session.ts

@@ -51,6 +51,8 @@ export interface SessionOptions {
   eventHubOptions?: EventHubOptions;
   clientToken?: string;
   apiEndpoint?: string;
+  additionalHeaders?: Data;
+  strictApi?: boolean;
 }
 
 export interface CreateComponentOptions {
@@ -95,11 +97,13 @@ export interface ResponseError {
 
 export interface MutatationOptions {
   pushToken?: string;
+  additionalHeaders?: Data;
 }
 
 export interface QueryOptions {
   abortController?: AbortController;
   signal?: AbortSignal;
+  additionalHeaders?: Data;
 }
 
 export interface CallOptions extends MutatationOptions, QueryOptions {}
@@ -121,6 +125,7 @@ export class Session {
   serverInformation?: Data;
   schemas?: Data;
   serverVersion?: string;
+  additionalHeaders: Data;
 
   /**
    * Construct Session instance with API credentials.
@@ -134,6 +139,8 @@ export class Session {
    * @param  {Object}  [options.eventHubOptions={}] - Options to configure event hub with.
    * @param  {string} [options.clientToken] - Client token for update events.
    * @param  {string} [options.apiEndpoint=/api] - API endpoint.
+   * @param {object} [options.headers] - Additional headers to send with the request
+   * @param {object} [options.strictApi] - Turn on strict API mode
    *
    * @constructs Session
    */
@@ -147,6 +154,8 @@ export class Session {
       eventHubOptions = {},
       clientToken,
       apiEndpoint = "/api",
+      additionalHeaders = {},
+      strictApi = false,
     }: SessionOptions = {}
   ) {
     if (!serverUrl || !apiUser || !apiKey) {
@@ -188,6 +197,21 @@ export class Session {
      */
     this.apiEndpoint = apiEndpoint;
 
+    /**
+     * allows setting additional headers to be sent with each request
+     * @memberof Session
+     * @instance
+     * @type {Data}
+     */
+    this.additionalHeaders = additionalHeaders;
+
+    if (strictApi) {
+      this.additionalHeaders = {
+        ...additionalHeaders,
+        "ftrack-strict-api": "true",
+      };
+    }
+
     /**
      * session event hub
      * @memberof Session
@@ -486,11 +510,17 @@ export class Session {
    * @param {AbortController} options.abortController - Abort controller, deprecated in favor of options.signal
    * @param {AbortSignal} options.signal - Abort signal
    * @param {string} options.pushToken - push token to associate with the request
+   * @param {object} options.headers - Additional headers to send with the request
    *
    */
   call(
     operations: operation.Operation[],
-    { abortController, pushToken, signal }: CallOptions = {}
+    {
+      abortController,
+      pushToken,
+      signal,
+      additionalHeaders = {},
+    }: CallOptions = {}
   ): Promise<Response<Data>[]> {
     const url = `${this.serverUrl}${this.apiEndpoint}`;
 
@@ -516,6 +546,8 @@ export class Session {
             "ftrack-user": this.apiUser,
             "ftrack-Clienttoken": this.clientToken,
             "ftrack-pushtoken": pushToken,
+            ...this.additionalHeaders,
+            ...additionalHeaders,
           } as HeadersInit,
           body: this.encodeOperations(operations),
           signal: abortController ? abortController.signal : signal,
@@ -701,12 +733,12 @@ export class Session {
    * @param {object} options
    * @param {object} options.abortController - Deprecated in favour of options.signal
    * @param {object} options.signal - Abort signal user for aborting requests prematurely
+   * @param {object} options.headers - Additional headers to send with the request
    * @return {Promise} Promise which will be resolved with an object
    * containing action, data and metadata
    */
   query(expression: string, options: QueryOptions = {}) {
     logger.debug("Query", expression);
-
     const queryOperation = operation.query(expression);
     let request = this.call([queryOperation], options).then((responses) => {
       const response = responses[0];
@@ -728,6 +760,7 @@ export class Session {
    * @param {object} additionalOptions
    * @param {object} options.abortController - Deprecated in favour of options.signal
    * @param {object} options.signal - Abort signal user for aborting requests prematurely
+   * @param {object} options.headers - Additional headers to send with the request
    * @return {Promise} Promise which will be resolved with an object
    * containing data and metadata
    */
@@ -771,6 +804,7 @@ export class Session {
    * @param {Object} data data which should be used to populate attributes on the entity.
    * @param {Object} options
    * @param {string} options.pushToken - push token to associate with the request
+   * @param {object} options.headers - Additional headers to send with the request
    * @return {Promise} Promise which will be resolved with the response.
    */
   create(entityType: string, data: Data, { pushToken }: CallOptions = {}) {
@@ -794,6 +828,7 @@ export class Session {
    * @param  {Object} data
    * @param {Object} options
    * @param {string} options.pushToken - push token to associate with the request
+   * @param {object} options.headers - Additional headers to send with the request
    * @return {Promise} Promise resolved with the response.
    */
   update(
@@ -821,6 +856,7 @@ export class Session {
    * @param  {Array} keys Identifying keys, typically [<entity id>]
    * @param {Object} options
    * @param {string} options.pushToken - push token to associate with the request
+   * @param {object} options.headers - Additional headers to send with the request
    * @return {Promise} Promise resolved with the response.
    */
   delete(type: string, keys: string[], { pushToken }: MutatationOptions = {}) {

test/server.js

@@ -4,6 +4,8 @@ import fs from "fs/promises";
 import querySchemas from "./fixtures/query_schemas.json";
 import queryServerInformation from "./fixtures/query_server_information.json";
 import getUploadMetadata from "./fixtures/get_upload_metadata.json";
+import exampleQuery from "./fixtures/query_select_name_from_task_limit_1.json";
+import { setupServer } from "msw/node";
 
 function authenticate(req) {
   // allow returning invalid authentication by setting ftrack-api-key to "INVALID_API_KEY"
@@ -21,7 +23,16 @@ function pick(object, keys) {
     return obj;
   }, {});
 }
-const handlers = [
+
+export function getInitialSessionQuery() {
+  return [queryServerInformation, querySchemas];
+}
+
+export function getExampleQuery() {
+  return [exampleQuery];
+}
+
+export const handlers = [
   rest.post("http://ftrack.test/api", async (req, res, ctx) => {
     if (!authenticate(req)) {
       return res(
@@ -111,4 +122,4 @@ const handlers = [
   }),
 ];
 
-export { handlers };
+export const server = setupServer(...handlers);

test/session.test.js

@@ -13,6 +13,9 @@ import { Session } from "../source/session";
 import * as operation from "../source/operation";
 import { expect } from "chai";
 
+import { getExampleQuery, getInitialSessionQuery, server } from "./server";
+import { rest } from "msw";
+
 const logger = loglevel.getLogger("test_session");
 logger.setLevel("debug");
 
@@ -64,6 +67,70 @@ describe("Session", () => {
         .then((response) => response.data[0].__entity_type__)
     ).resolves.toEqual("Task"));
 
+  it("Should allow adding additional headers on Session", async () => {
+    const headers = new Promise((resolve) => {
+      server.use(
+        rest.post("http://ftrack.test/api", (req, res, ctx) => {
+          resolve(req.headers);
+          return res.once(ctx.json(getInitialSessionQuery()));
+        })
+      );
+    });
+
+    new Session(
+      credentials.serverUrl,
+      credentials.apiUser,
+      credentials.apiKey,
+      {
+        autoConnectEventHub: false,
+        additionalHeaders: {
+          "X-Test-Header": "test",
+        },
+      }
+    );
+
+    return expect((await headers).get("X-Test-Header")).toEqual("test");
+  });
+
+  it("Should support strictApi option", async () => {
+    const headers = new Promise((resolve) => {
+      server.use(
+        rest.post("http://ftrack.test/api", (req, res, ctx) => {
+          resolve(req.headers);
+          return res.once(ctx.json(getInitialSessionQuery()));
+        })
+      );
+    });
+
+    new Session(
+      credentials.serverUrl,
+      credentials.apiUser,
+      credentials.apiKey,
+      {
+        autoConnectEventHub: false,
+        strictApi: true,
+      }
+    );
+
+    return expect((await headers).get("ftrack-strict-api")).toEqual("true");
+  });
+
+  it("Should allow adding additional headers on calls", async () => {
+    const headers = new Promise((resolve) => {
+      server.use(
+        rest.post("http://ftrack.test/api", (req, res, ctx) => {
+          resolve(req.headers);
+          return res.once(ctx.json(getExampleQuery()));
+        })
+      );
+    });
+
+    await session.query("select name from Task limit 1", {
+      additionalHeaders: { "X-Test-Header": "test" },
+    });
+    return expect((await headers).get("X-Test-Header")).toEqual("test");
+  });
+
   it("Should allow creating a User", () => {
     const promise = session.create("User", {
       username: getTestUsername(),

vitest.setup.js

@@ -1,8 +1,5 @@
 import { fetch } from "cross-fetch";
-import { setupServer } from "msw/node";
-import { handlers } from "./test/server";
-
-const server = setupServer(...handlers);
+import { server } from "./test/server";
 
 // Very simple mock of XmlHttpRequest with only the parts we use
 class MockXmlHttpRequest {