feat(sdk): better handling of token info and usage configuration (#6637)

Author: n1ru4l

.changeset/tiny-glasses-talk.md

@@ -0,0 +1,11 @@
+---
+'@graphql-hive/core': minor
+'@graphql-hive/apollo': minor
+'@graphql-hive/envelop': minor
+'@graphql-hive/yoga': minor
+---
+
+Add error logging for invalid combinations of the `target` and `token` configuration.
+
+- Please make sure to provide the `target` option for usage reporting when using a token that starts with `hvo1/`.
+- Please make sure to **not** provide a `target` option for usage reporting when a token does **not** start with `hvo1/`

packages/libraries/core/src/client/client.ts

@@ -53,10 +53,16 @@ export function createHive(options: HivePluginOptions): HiveClient {
     await Promise.all([schemaReporter.dispose(), usage.dispose()]);
   }
 
+  const isOrganizationAccessToken = options.token?.startsWith('hvo1/') === true;
+
   // enabledOnly when `printTokenInfo` is `true` or `debug` is true and `printTokenInfo` is not `false`
-  const printTokenInfo = enabled
-    ? options.printTokenInfo === true || (!!options.debug && options.printTokenInfo !== false)
-    : false;
+  const printTokenInfo =
+    enabled &&
+    /** Access tokens using the `hvo1/` prefix cannot print any token information. */
+    isOrganizationAccessToken === false
+      ? options.printTokenInfo === true || (!!options.debug && options.printTokenInfo !== false)
+      : false;
+
   const infoLogger = createHiveLogger(logger, '[info]');
 
   const info = printTokenInfo

packages/libraries/core/src/client/types.ts

@@ -234,6 +234,10 @@ export type HivePluginOptions = OptionalWhenFalse<
     /**
      * Print info about the token.
      * Disabled by default (enabled by default only in debug mode)
+     *
+     * **Note:** The new access tokens do not support printing the token info. For every access token starting with `hvo1/`
+     * no information will be printed.
+     * @deprecated This option will be removed in the future.
      */
     printTokenInfo?: boolean;
     /**

packages/libraries/core/src/client/usage.ts

@@ -51,16 +51,18 @@ function isAbortAction(result: Parameters<CollectUsageCallback>[1]): result is A
   return 'action' in result && result.action === 'abort';
 }
 
+const noopUsageCollector: UsageCollector = {
+  collect() {
+    return async () => {};
+  },
+  collectRequest() {},
+  async dispose() {},
+  collectSubscription() {},
+};
+
 export function createUsage(pluginOptions: HivePluginOptions): UsageCollector {
   if (!pluginOptions.usage || pluginOptions.enabled === false) {
-    return {
-      collect() {
-        return async () => {};
-      },
-      collectRequest() {},
-      async dispose() {},
-      collectSubscription() {},
-    };
+    return noopUsageCollector;
   }
 
   let reportSize = 0;
@@ -75,6 +77,23 @@ export function createUsage(pluginOptions: HivePluginOptions): UsageCollector {
   const collector = memo(createCollector, arg => arg.schema);
   const excludeSet = new Set(options.exclude ?? []);
 
+  /** Access tokens using the `hvo1/` require a target. */
+  if (!options.target && pluginOptions.token.startsWith('hvo1/')) {
+    logger.error(
+      "Using an organization access token (starting with 'hvo1/') requires providing the 'target' option." +
+        '\nUsage reporting is disabled.',
+    );
+    return noopUsageCollector;
+  }
+
+  if (options.target && !pluginOptions.token.startsWith('hvo1/')) {
+    logger.error(
+      "Using the 'target' option requires using an organization access token (starting with 'hvo1/')." +
+        '\nUsage reporting is disabled.',
+    );
+    return noopUsageCollector;
+  }
+
   const baseEndpoint =
     selfHostingOptions?.usageEndpoint ?? options.endpoint ?? 'https://app.graphql-hive.com/usage';
 

packages/libraries/core/tests/usage.spec.ts

@@ -750,7 +750,7 @@ test('retry on non-200', async () => {
 
 test('constructs URL with usage.target', async ({ expect }) => {
   const logger = createHiveTestingLogger();
-  const token = 'Token';
+  const token = 'hvo1/brrrrt';
   const dUrl = Promise.withResolvers<string>();
 
   const hive = createHive({