Move new top-level auth mode types out of js-client

Author: alanko0511

packages/api-client-core/spec/GadgetConnection-suite.ts

@@ -71,38 +71,6 @@ export const GadgetConnectionSharedSuite = (queryExtra = "") => {
   });
 
   describe("authorization", () => {
-    describe("when declaring authentication modes at the top level and under the `authenticationMode` key at the same time", () => {
-      it("should throw an error if same auth modes are declared", () => {
-        expect(
-          () =>
-            new GadgetConnection({
-              endpoint: "https://someapp.gadget.app/api/graphql",
-              authenticationMode: { browserSession: true },
-              browserSession: true,
-            } as any)
-        ).toThrowErrorMatchingInlineSnapshot(
-          `"Declaring authentication modes at the top level and under the \`authenticationMode\` key at the same time is not allowed."`
-        );
-      });
-
-      it("should throw an error if different auth modes are declared", () => {
-        expect(
-          () =>
-            new GadgetConnection({
-              endpoint: "https://someapp.gadget.app/api/graphql",
-              authenticationMode: {
-                browserSession: {
-                  shopId: "1234",
-                },
-              },
-              anonymous: true,
-            } as any)
-        ).toThrowErrorMatchingInlineSnapshot(
-          `"Declaring authentication modes at the top level and under the \`authenticationMode\` key at the same time is not allowed."`
-        );
-      });
-    });
-
     it("should allow connecting with anonymous authentication", async () => {
       nock("https://someapp.gadget.app")
         .post("/api/graphql?operation=meta", { query: `{\n  meta {\n    appName\n${queryExtra}  }\n}`, variables: {} })
@@ -806,8 +774,10 @@ export const GadgetConnectionSharedSuite = (queryExtra = "") => {
 
       const connection = new GadgetConnection({
         endpoint: "https://someapp.gadget.app/api/graphql",
-        browserSession: {
-          shopId: "1234",
+        authenticationMode: {
+          browserSession: {
+            shopId: "1234",
+          },
         },
       });
 

packages/api-client-core/src/ClientOptions.ts

@@ -1,11 +1,16 @@
 import type { Exchange } from "@urql/core";
 import type { GadgetSubscriptionClientOptions } from "./GadgetConnection.js";
 
-type BaseClientOptions = {
+/** All the options for a Gadget client */
+export interface ClientOptions {
   /**
    *  The HTTP GraphQL endpoint this connection should connect to
    **/
   endpoint?: string;
+  /**
+   * The authentication strategy for connecting to the upstream API
+   **/
+  authenticationMode?: AuthenticationModeOptions;
   /**
    * The Websockets GraphQL endpoint this connection should connect to for transactional processing
    **/
@@ -40,24 +45,7 @@ type BaseClientOptions = {
    * A list of exchanges to merge into the default exchanges used by the client.
    */
   exchanges?: Exchanges;
-};
-
-/** All the options for a Gadget client */
-export type ClientOptions = BaseClientOptions &
-  (
-    | {
-        /**
-         * The authentication strategy for connecting to the upstream API.
-         *
-         * Note: you can only declare authentication modes at the top level, or under the `authenticationMode` key.
-         * If you declare them at the top level and under the `authenticationMode` key at the same time, an error will be thrown.
-         **/
-        authenticationMode?: AuthenticationModeOptions;
-      }
-    | ({
-        authenticationMode?: never;
-      } & AuthenticationModeOptions)
-  );
+}
 
 /** Options to configure a specific browser-based authentication mode */
 export interface BrowserSessionAuthenticationModeOptions {
@@ -95,46 +83,31 @@ export enum BrowserSessionStorageType {
   Temporary = "temporary",
 }
 
-/** Describes how to authenticate an instance of the client with the Gadget platform. */
+/** Describes how to authenticate an instance of the client with the Gadget platform */
 export interface AuthenticationModeOptions {
-  /**
-   * Use an API key to authenticate with Gadget.
-   * It's not strictly required, but without this the client might be useless depending on the app's permissions.
-   */
+  // Use an API key to authenticate with Gadget.
+  // Not strictly required, but without this the client might be useless depending on the app's permissions.
   apiKey?: string;
 
-  /**
-   * Use a web browser's `localStorage` or `sessionStorage` to persist authentication information.
-   * This allows the browser to have a persistent identity as the user navigates around and logs in and out.
-   */
+  // Use a web browser's `localStorage` or `sessionStorage` to persist authentication information.
+  // This allows the browser to have a persistent identity as the user navigates around and logs in and out.
   browserSession?: boolean | BrowserSessionAuthenticationModeOptions;
 
-  /**
-   * Use no authentication at all, and get access only to the data that the Unauthenticated backend role has access to.
-   */
+  // Use no authentication at all, and get access only to the data that the Unauthenticated backend role has access to.
   anonymous?: true;
 
-  /**
-   * @deprecated Use internal instead.
-   */
+  // @deprecated Use internal instead
   internalAuthToken?: string;
 
-  /**
-   * Use an internal platform auth token for authentication
-   * This is used to communicate within Gadget itself and shouldn't be used to connect to Gadget from other systems.
-   * @private
-   */
+  // @private Use an internal platform auth token for authentication
+  // This is used to communicate within Gadget itself and shouldn't be used to connect to Gadget from other systems
   internal?: {
     authToken: string;
     actAsSession?: boolean;
     getSessionId?: () => Promise<string | undefined>;
   };
 
-  /**
-   * Use a passed custom function for managing authentication.
-   * For some fancy integrations that the API client supports, like embedded Shopify apps, we use platform native features to authenticate with the Gadget backend.
-   * @private
-   */
+  // @private Use a passed custom function for managing authentication. For some fancy integrations that the API client supports, like embedded Shopify apps, we use platform native features to authenticate with the Gadget backend.
   custom?: {
     processFetch(input: RequestInfo | URL, init: RequestInit): Promise<void>;
     processTransactionConnectionParams(params: Record<string, any>): Promise<void>;

packages/api-client-core/src/GadgetConnection.ts

@@ -19,9 +19,7 @@ import {
   GadgetTooManyRequestsError,
   GadgetUnexpectedCloseError,
   GadgetWebsocketConnectionTimeoutError,
-  availableAuthenticationModes,
   isCloseEvent,
-  maybeGetAuthenticationModeOptionsFromConnectionOptions,
   storageAvailable,
 } from "./support.js";
 
@@ -48,8 +46,9 @@ export const $gadgetConnection = Symbol.for("gadget/connection");
 const sessionStorageKey = "token";
 const base64 = typeof btoa !== "undefined" ? btoa : (str: string) => Buffer.from(str).toString("base64");
 
-type BaseGadgetConnectionOptions = {
+export interface GadgetConnectionOptions {
   endpoint: string;
+  authenticationMode?: AuthenticationModeOptions;
   websocketsEndpoint?: string;
   subscriptionClientOptions?: GadgetSubscriptionClientOptions;
   websocketImplementation?: typeof globalThis.WebSocket;
@@ -60,17 +59,7 @@ type BaseGadgetConnectionOptions = {
   baseRouteURL?: string;
   exchanges?: Exchanges;
   createSubscriptionClient?: typeof createSubscriptionClient;
-};
-
-export type GadgetConnectionOptions = BaseGadgetConnectionOptions &
-  (
-    | {
-        authenticationMode?: AuthenticationModeOptions;
-      }
-    | ({
-        authenticationMode?: never;
-      } & AuthenticationModeOptions)
-  );
+}
 
 /**
  * Represents the current strategy for authenticating with the Gadget platform.
@@ -95,7 +84,6 @@ const objectForGlobals = typeof globalThis != "undefined" ? globalThis : typeof
  */
 export class GadgetConnection {
   static version = "<prerelease>" as const;
-  static availableAuthenticationModes = availableAuthenticationModes;
 
   // Options used when generating new GraphQL clients for the base connection and for for transactions
   readonly endpoint: string;
@@ -121,15 +109,7 @@ export class GadgetConnection {
   private requestPolicy: RequestPolicy;
   createSubscriptionClient: typeof createSubscriptionClient;
 
-  /**
-   * The authentication mode that came from the connection options in the constructor.
-   * We have two methods of setting the authentication mode, so we're storing it separately to avoid having to manually determine which method was used.
-   */
-  private authenticationModeOptions?: AuthenticationModeOptions;
-
   constructor(readonly options: GadgetConnectionOptions) {
-    this.authenticationModeOptions = maybeGetAuthenticationModeOptionsFromConnectionOptions(options);
-
     if (!options.endpoint) throw new Error("Must provide an `endpoint` option for a GadgetConnection to connect to");
     this.endpoint = options.endpoint;
     if (options.fetchImplementation) {
@@ -161,7 +141,7 @@ export class GadgetConnection {
     };
     this.createSubscriptionClient = options.createSubscriptionClient ?? createSubscriptionClient;
 
-    this.setAuthenticationMode(this.authenticationModeOptions);
+    this.setAuthenticationMode(options.authenticationMode);
 
     this.baseClient = this.newBaseClient();
   }
@@ -196,7 +176,7 @@ export class GadgetConnection {
       } else if (options.custom) {
         this.authenticationMode = AuthenticationMode.Custom;
       }
-      this.authenticationModeOptions = options;
+      this.options.authenticationMode = options;
     }
 
     this.authenticationMode ??= AuthenticationMode.Anonymous;
@@ -337,7 +317,7 @@ export class GadgetConnection {
       init.headers = { ...requestHeaders, ...init.headers };
 
       if (this.authenticationMode == AuthenticationMode.Custom) {
-        await this.authenticationModeOptions!.custom!.processFetch(input, init);
+        await this.options.authenticationMode!.custom!.processFetch(input, init);
       }
     }
 
@@ -491,24 +471,24 @@ export class GadgetConnection {
         // In the browser, we can't set arbitrary headers on the websocket request, so we don't use the same auth mechanism that we use for normal HTTP requests. Instead we use graphql-ws' connectionParams to send the auth information in the connection setup message to the server.
         const connectionParams: Record<string, any> = { environment: this.environment, auth: { type: this.authenticationMode } };
         if (this.authenticationMode == AuthenticationMode.APIKey) {
-          connectionParams.auth.key = this.authenticationModeOptions!.apiKey!;
+          connectionParams.auth.key = this.options.authenticationMode!.apiKey!;
         } else if (
           this.authenticationMode == AuthenticationMode.Internal ||
           this.authenticationMode == AuthenticationMode.InternalAuthToken
         ) {
           const authToken =
             this.authenticationMode == AuthenticationMode.Internal
-              ? this.authenticationModeOptions!.internal!.authToken
-              : this.authenticationModeOptions!.internalAuthToken!;
+              ? this.options.authenticationMode!.internal!.authToken
+              : this.options.authenticationMode!.internalAuthToken!;
           connectionParams.auth.token = authToken;
-          if (this.authenticationMode == AuthenticationMode.Internal && this.authenticationModeOptions!.internal!.actAsSession) {
+          if (this.authenticationMode == AuthenticationMode.Internal && this.options.authenticationMode!.internal!.actAsSession) {
             connectionParams.auth.actAsInternalSession = true;
-            connectionParams.auth.internalSessionId = await this.authenticationModeOptions!.internal!.getSessionId?.();
+            connectionParams.auth.internalSessionId = await this.options.authenticationMode!.internal!.getSessionId?.();
           }
         } else if (this.authenticationMode == AuthenticationMode.BrowserSession) {
           connectionParams.auth.sessionToken = this.sessionTokenStore!.getItem(this.sessionStorageKey);
         } else if (this.authenticationMode == AuthenticationMode.Custom) {
-          await this.authenticationModeOptions?.custom?.processTransactionConnectionParams(connectionParams);
+          await this.options.authenticationMode?.custom?.processTransactionConnectionParams(connectionParams);
         }
         return connectionParams;
       },
@@ -519,11 +499,8 @@ export class GadgetConnection {
         connected: (socket, payload) => {
           // If we're using session token authorization, we don't use request headers to exchange the session token, we use graphql-ws' ConnectionAck payload to persist the token. When the subscription client first starts, the server will send us session token identifying this client, and we persist it to the session token store
           if (this.authenticationMode == AuthenticationMode.BrowserSession && payload?.sessionToken) {
-            const browserSession = this.authenticationModeOptions?.browserSession;
-            const initialToken =
-              browserSession !== null && typeof browserSession === "object" && "initialToken" in browserSession
-                ? browserSession.initialToken
-                : null;
+            const browserSession = this.options.authenticationMode?.browserSession;
+            const initialToken = browserSession !== null && typeof browserSession === "object" ? browserSession.initialToken : null;
             if (!initialToken) {
               this.sessionTokenStore!.setItem(this.sessionStorageKey, payload.sessionToken as string);
             }
@@ -556,28 +533,28 @@ export class GadgetConnection {
     if (this.authenticationMode == AuthenticationMode.Internal || this.authenticationMode == AuthenticationMode.InternalAuthToken) {
       const authToken =
         this.authenticationMode == AuthenticationMode.Internal
-          ? this.authenticationModeOptions!.internal!.authToken
-          : this.authenticationModeOptions!.internalAuthToken!;
+          ? this.options.authenticationMode!.internal!.authToken
+          : this.options.authenticationMode!.internalAuthToken!;
 
       headers.authorization = "Basic " + base64("gadget-internal" + ":" + authToken);
 
-      if (this.authenticationMode == AuthenticationMode.Internal && this.authenticationModeOptions!.internal!.actAsSession) {
+      if (this.authenticationMode == AuthenticationMode.Internal && this.options.authenticationMode!.internal!.actAsSession) {
         headers["x-gadget-act-as-internal-session"] = "true";
 
-        const sessionId = await this.authenticationModeOptions!.internal!.getSessionId?.();
+        const sessionId = await this.options.authenticationMode!.internal!.getSessionId?.();
         if (sessionId) {
           headers["x-gadget-internal-session-id"] = sessionId;
         }
       }
     } else if (this.authenticationMode == AuthenticationMode.APIKey) {
-      headers.authorization = `Bearer ${this.authenticationModeOptions?.apiKey}`;
+      headers.authorization = `Bearer ${this.options.authenticationMode?.apiKey}`;
     } else if (this.authenticationMode == AuthenticationMode.BrowserSession) {
       const val = this.sessionTokenStore!.getItem(this.sessionStorageKey);
       if (val) {
         headers.authorization = `Session ${val}`;
       }
 
-      const browserSessionOptions = this.authenticationModeOptions!.browserSession!;
+      const browserSessionOptions = this.options.authenticationMode!.browserSession!;
       const shopId = typeof browserSessionOptions === "boolean" ? undefined : browserSessionOptions.shopId;
       if (shopId) {
         headers["x-gadget-for-shop-id"] = shopId;

packages/api-client-core/src/support.ts

@@ -1,9 +1,7 @@
 import type { OperationResult } from "@urql/core";
 import { CombinedError } from "@urql/core";
 import { Call, type FieldSelection as BuilderFieldSelection } from "tiny-graphql-query-compiler";
-import type { AuthenticationModeOptions, ClientOptions } from "./ClientOptions.js";
 import { DataHydrator } from "./DataHydrator.js";
-import type { GadgetConnectionOptions } from "./GadgetConnection.js";
 import type { ActionFunctionMetadata, AnyActionFunction } from "./GadgetFunctions.js";
 import type { RecordShape } from "./GadgetRecord.js";
 import { GadgetRecord } from "./GadgetRecord.js";
@@ -754,40 +752,3 @@ export const formatErrorMessages = (error: Error) => {
 
   return result;
 };
-
-export const availableAuthenticationModes = [
-  "apiKey",
-  "browserSession",
-  "anonymous",
-  "internalAuthToken",
-  "internal",
-  "custom",
-] as const satisfies readonly (keyof AuthenticationModeOptions)[];
-
-// Type assertion to ensure all `AuthenticationModeOptions` keys are included in the `availableAuthenticationModes` array
-type MissingKeys = Exclude<keyof AuthenticationModeOptions, (typeof availableAuthenticationModes)[number]>;
-type _AssertAllKeysIncluded = [MissingKeys] extends [never] ? true : `Missing keys: ${MissingKeys}`;
-const _assertAllAuthKeysIncluded: _AssertAllKeysIncluded = true as _AssertAllKeysIncluded;
-
-export const maybeGetAuthenticationModeOptionsFromConnectionOptions = (
-  options: GadgetConnectionOptions | ClientOptions
-): AuthenticationModeOptions | undefined => {
-  const topLevelAuthModes: AuthenticationModeOptions = {};
-  for (const key of availableAuthenticationModes) {
-    if (key in options) {
-      topLevelAuthModes[key] = (options as any)[key];
-    }
-  }
-
-  if ("authenticationMode" in options && Object.keys(topLevelAuthModes).length > 0) {
-    throw new GadgetClientError(
-      "Declaring authentication modes at the top level and under the `authenticationMode` key at the same time is not allowed."
-    );
-  }
-
-  if ("authenticationMode" in options) {
-    return options.authenticationMode;
-  }
-
-  return topLevelAuthModes;
-};