Introduce shopId in browserSession to set shop tenant

Author: alanko0511

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

@@ -756,6 +756,45 @@ export const GadgetConnectionSharedSuite = (queryExtra = "") => {
       expect(customResult.error).toBeUndefined();
       expect(customResult.data).toEqual({ meta: { appName: "some app" } });
     });
+
+    it("should support browser session with shop tenant", async () => {
+      nock("https://someapp.gadget.app")
+        .post("/api/graphql?operation=meta", { query: `{\n  meta {\n    appName\n${queryExtra}  }\n}`, variables: {} })
+        .reply(200, function () {
+          expect(this.req.headers["x-gadget-for-shop-id"]).toEqual(["1234"]);
+
+          return {
+            data: {
+              meta: {
+                appName: "some app",
+              },
+            },
+          };
+        });
+
+      const connection = new GadgetConnection({
+        endpoint: "https://someapp.gadget.app/api/graphql",
+        browserSession: {
+          shopId: "1234",
+        },
+      });
+
+      const result = await connection.currentClient
+        .query(
+          gql`
+            {
+              meta {
+                appName
+              }
+            }
+          `,
+          {}
+        )
+        .toPromise();
+
+      expect(result.error).toBeUndefined();
+      expect(result.data).toEqual({ meta: { appName: "some app" } });
+    });
   });
 
   describe("raw fetching", () => {

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

@@ -2,15 +2,11 @@ import type { Exchange } from "@urql/core";
 import type { GadgetSubscriptionClientOptions } from "./GadgetConnection.js";
 
 /** All the options for a Gadget client */
-export interface ClientOptions {
+export type 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
    **/
@@ -45,7 +41,15 @@ export interface ClientOptions {
    * A list of exchanges to merge into the default exchanges used by the client.
    */
   exchanges?: Exchanges;
-}
+} & (
+  | {
+      /**
+       * The authentication strategy for connecting to the upstream API
+       **/
+      authenticationMode?: AuthenticationModeOptions;
+    }
+  | AuthenticationModeOptions
+);
 
 /** Options to configure a specific browser-based authentication mode */
 export interface BrowserSessionAuthenticationModeOptions {
@@ -58,7 +62,11 @@ export interface BrowserSessionAuthenticationModeOptions {
   /**
    * Configures how the authentication token is persisted. See `BrowserSessionStorageType`.
    */
-  storageType: BrowserSessionStorageType;
+  storageType?: BrowserSessionStorageType;
+  /**
+   * The shop ID to set shop tenant. Useful for fetching shop-specific data.
+   */
+  shopId?: string;
 }
 
 /**
@@ -81,29 +89,44 @@ export enum BrowserSessionStorageType {
 
 /** Describes how to authenticate an instance of the client with the Gadget platform */
 export interface AuthenticationModeOptions {
-  // 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.
+  /**
+   * 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.
+   */
   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;
 
-  // @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
+  /**
+   * 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
+   */
   internal?: {
     authToken: string;
     actAsSession?: boolean;
     getSessionId?: () => Promise<string | undefined>;
   };
 
-  // @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.
+  /**
+   * 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
+   */
   custom?: {
     processFetch(input: RequestInfo | URL, init: RequestInit): Promise<void>;
     processTransactionConnectionParams(params: Record<string, any>): Promise<void>;

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

@@ -19,7 +19,9 @@ import {
   GadgetTooManyRequestsError,
   GadgetUnexpectedCloseError,
   GadgetWebsocketConnectionTimeoutError,
+  availableAuthenticationModes,
   isCloseEvent,
+  maybeGetAuthenticationModeOptionsFromConnectionOptions,
   storageAvailable,
 } from "./support.js";
 
@@ -46,9 +48,8 @@ export const $gadgetConnection = Symbol.for("gadget/connection");
 const sessionStorageKey = "token";
 const base64 = typeof btoa !== "undefined" ? btoa : (str: string) => Buffer.from(str).toString("base64");
 
-export interface GadgetConnectionOptions {
+export type GadgetConnectionOptions = {
   endpoint: string;
-  authenticationMode?: AuthenticationModeOptions;
   websocketsEndpoint?: string;
   subscriptionClientOptions?: GadgetSubscriptionClientOptions;
   websocketImplementation?: typeof globalThis.WebSocket;
@@ -59,7 +60,12 @@ export interface GadgetConnectionOptions {
   baseRouteURL?: string;
   exchanges?: Exchanges;
   createSubscriptionClient?: typeof createSubscriptionClient;
-}
+} & (
+  | {
+      authenticationMode?: AuthenticationModeOptions;
+    }
+  | AuthenticationModeOptions
+);
 
 /**
  * Represents the current strategy for authenticating with the Gadget platform.
@@ -84,6 +90,7 @@ 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;
@@ -109,7 +116,15 @@ 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) {
@@ -141,7 +156,7 @@ export class GadgetConnection {
     };
     this.createSubscriptionClient = options.createSubscriptionClient ?? createSubscriptionClient;
 
-    this.setAuthenticationMode(options.authenticationMode);
+    this.setAuthenticationMode(this.authenticationModeOptions);
 
     this.baseClient = this.newBaseClient();
   }
@@ -176,7 +191,7 @@ export class GadgetConnection {
       } else if (options.custom) {
         this.authenticationMode = AuthenticationMode.Custom;
       }
-      this.options.authenticationMode = options;
+      this.authenticationModeOptions = options;
     }
 
     this.authenticationMode ??= AuthenticationMode.Anonymous;
@@ -185,7 +200,8 @@ export class GadgetConnection {
   enableSessionMode(options?: true | BrowserSessionAuthenticationModeOptions) {
     this.authenticationMode = AuthenticationMode.BrowserSession;
 
-    const desiredMode = !options || typeof options == "boolean" ? BrowserSessionStorageType.Durable : options.storageType;
+    const desiredMode =
+      !options || typeof options == "boolean" || !("storageType" in options) ? BrowserSessionStorageType.Durable : options.storageType;
     let sessionTokenStore;
     if (desiredMode == BrowserSessionStorageType.Durable && storageAvailable("localStorage")) {
       sessionTokenStore = window.localStorage;
@@ -316,7 +332,7 @@ export class GadgetConnection {
       init.headers = { ...requestHeaders, ...init.headers };
 
       if (this.authenticationMode == AuthenticationMode.Custom) {
-        await this.options.authenticationMode!.custom!.processFetch(input, init);
+        await this.authenticationModeOptions!.custom!.processFetch(input, init);
       }
     }
 
@@ -470,24 +486,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.options.authenticationMode!.apiKey!;
+          connectionParams.auth.key = this.authenticationModeOptions!.apiKey!;
         } else if (
           this.authenticationMode == AuthenticationMode.Internal ||
           this.authenticationMode == AuthenticationMode.InternalAuthToken
         ) {
           const authToken =
             this.authenticationMode == AuthenticationMode.Internal
-              ? this.options.authenticationMode!.internal!.authToken
-              : this.options.authenticationMode!.internalAuthToken!;
+              ? this.authenticationModeOptions!.internal!.authToken
+              : this.authenticationModeOptions!.internalAuthToken!;
           connectionParams.auth.token = authToken;
-          if (this.authenticationMode == AuthenticationMode.Internal && this.options.authenticationMode!.internal!.actAsSession) {
+          if (this.authenticationMode == AuthenticationMode.Internal && this.authenticationModeOptions!.internal!.actAsSession) {
             connectionParams.auth.actAsInternalSession = true;
-            connectionParams.auth.internalSessionId = await this.options.authenticationMode!.internal!.getSessionId?.();
+            connectionParams.auth.internalSessionId = await this.authenticationModeOptions!.internal!.getSessionId?.();
           }
         } else if (this.authenticationMode == AuthenticationMode.BrowserSession) {
           connectionParams.auth.sessionToken = this.sessionTokenStore!.getItem(this.sessionStorageKey);
         } else if (this.authenticationMode == AuthenticationMode.Custom) {
-          await this.options.authenticationMode?.custom?.processTransactionConnectionParams(connectionParams);
+          await this.authenticationModeOptions?.custom?.processTransactionConnectionParams(connectionParams);
         }
         return connectionParams;
       },
@@ -498,8 +514,11 @@ 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.options.authenticationMode?.browserSession;
-            const initialToken = browserSession !== null && typeof browserSession === "object" ? browserSession.initialToken : null;
+            const browserSession = this.authenticationModeOptions?.browserSession;
+            const initialToken =
+              browserSession !== null && typeof browserSession === "object" && "initialToken" in browserSession
+                ? browserSession.initialToken
+                : null;
             if (!initialToken) {
               this.sessionTokenStore!.setItem(this.sessionStorageKey, payload.sessionToken as string);
             }
@@ -532,26 +551,32 @@ export class GadgetConnection {
     if (this.authenticationMode == AuthenticationMode.Internal || this.authenticationMode == AuthenticationMode.InternalAuthToken) {
       const authToken =
         this.authenticationMode == AuthenticationMode.Internal
-          ? this.options.authenticationMode!.internal!.authToken
-          : this.options.authenticationMode!.internalAuthToken!;
+          ? this.authenticationModeOptions!.internal!.authToken
+          : this.authenticationModeOptions!.internalAuthToken!;
 
       headers.authorization = "Basic " + base64("gadget-internal" + ":" + authToken);
 
-      if (this.authenticationMode == AuthenticationMode.Internal && this.options.authenticationMode!.internal!.actAsSession) {
+      if (this.authenticationMode == AuthenticationMode.Internal && this.authenticationModeOptions!.internal!.actAsSession) {
         headers["x-gadget-act-as-internal-session"] = "true";
 
-        const sessionId = await this.options.authenticationMode!.internal!.getSessionId?.();
+        const sessionId = await this.authenticationModeOptions!.internal!.getSessionId?.();
         if (sessionId) {
           headers["x-gadget-internal-session-id"] = sessionId;
         }
       }
     } else if (this.authenticationMode == AuthenticationMode.APIKey) {
-      headers.authorization = `Bearer ${this.options.authenticationMode?.apiKey}`;
+      headers.authorization = `Bearer ${this.authenticationModeOptions?.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 shopId = typeof browserSessionOptions === "boolean" ? undefined : browserSessionOptions.shopId;
+      if (shopId) {
+        headers["x-gadget-for-shop-id"] = shopId;
+      }
     }
 
     headers["x-gadget-environment"] = this.environment;

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

@@ -1,7 +1,9 @@
 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";
@@ -752,3 +754,33 @@ 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 => {
+  if ("authenticationMode" in options) {
+    return options.authenticationMode;
+  }
+
+  const result: AuthenticationModeOptions = {};
+  for (const key of availableAuthenticationModes) {
+    if (key in options) {
+      result[key] = (options as any)[key];
+    }
+  }
+  return result;
+};