feat: reduce debug logging noise

Author: marcomontalbano

biome.json

@@ -18,7 +18,10 @@
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true
+      "recommended": true,
+      "style": {
+        "useBlockStatements": "error"
+      }
     }
   },
   "javascript": {

examples/bun/blog-1.ts

@@ -28,7 +28,7 @@ const salesChannel = makeSalesChannel(
   {
     clientId: "<your_client_id>",
     scope: "<your_scope>",
-    debug: true, // useful to understand what happens behind the scene
+    debug: { logLevel: "info" }, // useful to understand what happens behind the scene
   },
   {
     storage: memoryStorage(),

examples/bun/blog-2.ts

@@ -37,7 +37,7 @@ const integration = makeIntegration(
   {
     clientId: "<your_client_id>",
     clientSecret: "<your_client_secret>",
-    debug: true,
+    debug: { logLevel: "info" },
   },
   {
     storage: compositeStorage,

examples/nextjs/src/app/api-credentials/client/page.tsx

@@ -1,9 +1,12 @@
 "use client"
 
-import DefaultTemplate from "@/components/DefaultTemplate"
-import { CommerceLayerAuthProvider, useCommerceLayerAuth } from "@/contexts/CommerceLayerAuthContext"
 import { getCoreApiBaseEndpoint, jwtDecode } from "@commercelayer/js-auth"
 import { useEffect, useMemo, useState } from "react"
+import DefaultTemplate from "@/components/DefaultTemplate"
+import {
+  CommerceLayerAuthProvider,
+  useCommerceLayerAuth,
+} from "@/contexts/CommerceLayerAuthContext"
 
 const scope = process.env.NEXT_PUBLIC_SCOPE as string
 
@@ -153,7 +156,12 @@ function CustomerOrders() {
     } else {
       setOrders(null)
     }
-  }, [authorization.accessToken, authorization.ownerType, authorization.ownerId, organizationSlug])
+  }, [
+    authorization.accessToken,
+    authorization.ownerType,
+    authorization.ownerId,
+    organizationSlug,
+  ])
 
   if (orders == null) {
     return null

examples/nextjs/src/app/utils/getServerSideToken.ts

@@ -12,10 +12,15 @@ const salesChannel = makeSalesChannel(
   {
     clientId,
     scope,
-    debug: true,
+    debug: {
+      logLevel: "verbose",
+    },
   },
   {
     storage: createCompositeStorage({
+      debug: {
+        logLevel: "verbose",
+      },
       name: "serverCompositeStorage",
       storages: [
         createStorage({
@@ -34,7 +39,9 @@ const salesChannel = makeSalesChannel(
   },
 )
 
-export async function getServerSideAuth(): Promise<ReturnType<typeof makeSalesChannel>> {
+export async function getServerSideAuth(): Promise<
+  ReturnType<typeof makeSalesChannel>
+> {
   "use server"
 
   return {

examples/nextjs/src/contexts/CommerceLayerAuthContext.tsx

@@ -5,7 +5,7 @@ import {
   authenticate,
   makeSalesChannel,
 } from "@commercelayer/js-auth"
-import cookies from 'js-cookie'
+import cookies from "js-cookie"
 import {
   createContext,
   type ReactNode,
@@ -22,11 +22,14 @@ type AuthState = {
   accessToken?: string
   ownerType?: "customer" | "guest"
   ownerId?: string
-  errors?: Extract<AuthenticateReturn<'password'>, { errors?: unknown }>['errors']
+  errors?: Extract<
+    AuthenticateReturn<"password">,
+    { errors?: unknown }
+  >["errors"]
 }
 
 interface CommerceLayerAuthContextType extends AuthState {
-  login: ( email: string, password: string ) => Promise<void>
+  login: (email: string, password: string) => Promise<void>
   logout: () => Promise<void>
 }
 
@@ -46,7 +49,10 @@ export function useCommerceLayerAuth() {
 export function CommerceLayerAuthProvider({
   children,
   scope,
-}: { children: ReactNode; scope: string }) {
+}: {
+  children: ReactNode
+  scope: string
+}) {
   const [salesChannel, setSalesChannel] =
     useState<ReturnType<typeof makeSalesChannel>>()
 
@@ -58,7 +64,9 @@ export function CommerceLayerAuthProvider({
         {
           clientId,
           scope,
-          debug: true,
+          debug: {
+            logLevel: "verbose",
+          },
         },
         {
           storage: createStorage({
@@ -111,7 +119,10 @@ export function CommerceLayerAuthProvider({
       setAuth({
         accessToken: authorization.accessToken,
         ownerType: authorization.ownerType,
-        ownerId: authorization.ownerType === 'customer' ? authorization.ownerId : undefined,
+        ownerId:
+          authorization.ownerType === "customer"
+            ? authorization.ownerId
+            : undefined,
         errors: authorization.errors,
       })
     },
@@ -132,10 +143,7 @@ export function CommerceLayerAuthProvider({
     void salesChannel?.getAuthorization().then((auth) => {
       setAuth({
         ownerType: auth.ownerType,
-        ownerId:
-          auth.ownerType === "customer"
-            ? auth.ownerId
-            : undefined,
+        ownerId: auth.ownerType === "customer" ? auth.ownerId : undefined,
         accessToken: auth.accessToken,
         errors: auth.errors,
       })

examples/nextjs/src/proxies/withCommerceLayer.ts

@@ -47,7 +47,9 @@ export const withCommerceLayer: WithProxy = (
         {
           clientId,
           scope,
-          debug: true,
+          debug: {
+            logLevel: "verbose",
+          },
         },
         {
           storage: createStorage({

packages/js-auth/README.md

@@ -175,7 +175,9 @@ const salesChannel = makeSalesChannel(
   {
     clientId: "<your_client_id>",
     scope: "market:code:europe",
-    debug: true,
+    debug: {
+      logLevel: "info"
+    },
   },
   {
     storage: memoryStorage(),
@@ -249,19 +251,32 @@ flowchart TB
 
 You can enable debugging and assign custom names to your storage instances for better visibility into token operations:
 
-- **`debug`** — When set to `true`, logs detailed information about token operations (creation, retrieval, refresh, etc.).
+- **`debug`** — Accepts a `DebugConfig` object with two options:
+  - `logLevel: "info"` — logs meaningful events only: cache misses, token refreshes, authorizations stored/removed, and errors. Routine cache hits are silent, so setups that call `getAuthorization()` on every API request don't flood the logs.
+  - `logLevel: "verbose"` — also logs steady-state operations (every storage read and cache hit).
+  - `maskToken` — whether to mask access tokens and refresh tokens in the log output (e.g. `eyJh...A9Xz`). Defaults to `true`. Set to `false` to see full tokens, e.g. for inspecting them at [jwt.io](https://jwt.io).
 - **`name`** — A custom identifier for your storage instance, useful when using multiple storages or composite storage configurations. The `name` is an attribute of the storage itself (as shown in the [`memoryStorage` example above](#storage-strategy)).
 
+The `createCompositeStorage` helper accepts its own `debug` option, following the same rule: a hit on the first (fastest) storage is steady state, while falling back to a slower storage is a meaningful event worth logging.
+
+> [!WARNING]
+> When `maskToken` is set to `false`, full access tokens and refresh tokens are logged to the console. Intended for local development only — in serverless/edge environments, logs may be forwarded to external log aggregation services.
+
 ```diff
  const salesChannel = makeSalesChannel(
    {
      clientId: "<your_client_id>",
      scope: "market:code:europe",
-+    debug: true,
++    debug: {
++      logLevel: "info"
++    },
    },
    {
      storage: {
 +      name: "storage-name",
++      debug: {
++        logLevel: "info"
++      },
        async getItem(key) {
          // implementation
        },
@@ -499,7 +514,9 @@ const integration = makeIntegration(
   {
     clientId: "<your_client_id>",
     clientSecret: "<your_client_secret>",
-    debug: true,
+    debug: {
+      logLevel: "info"
+    },
   },
   {
     storage: compositeStorage,