feat: reduce debug logging noise and add helper

Author: marcomontalbano

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,11 @@ const salesChannel = makeSalesChannel(
   {
     clientId,
     scope,
-    debug: true,
+    debug: "verbose",
   },
   {
     storage: createCompositeStorage({
+      debug: "verbose",
       name: "serverCompositeStorage",
       storages: [
         createStorage({
@@ -34,7 +35,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>>()
 
@@ -111,7 +117,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 +141,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,
       })

packages/js-auth/README.md

@@ -26,6 +26,7 @@ It works everywhere — on your browser, server, or at the edge.
 - [Utilities](#utilities)
   - [Revoking a token](#revoking-a-token)
   - [Decoding an access token](#decoding-an-access-token)
+  - [Checking if an access token is expired](#checking-if-an-access-token-is-expired)
   - [Verifying an access token](#verifying-an-access-token)
   - [Getting the Core API base endpoint](#getting-the-core-api-base-endpoint)
   - [Getting the Provisioning API base endpoint](#getting-the-provisioning-api-base-endpoint)
@@ -249,9 +250,14 @@ 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`** — When set to `true`, logs **state transitions** only: cache misses, token refreshes, authorizations stored/removed, and errors. Routine cache hits are silent, so setups that call `getAuthorization()` on every API request (e.g. when implementing the SDK's `getAccessToken` callback) don't flood the logs. Set it to `"verbose"` to also log steady-state operations (every storage read and cache hit).
 - **`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 transition worth logging.
+
+> [!WARNING]
+> When debug mode is enabled, full authorization objects (including access tokens and refresh tokens) are logged to the console. It is intended for local development only — in serverless/edge environments, logs may be forwarded to external log aggregation services.
+
 ```diff
  const salesChannel = makeSalesChannel(
    {
@@ -671,6 +677,20 @@ if (jwtIsSalesChannel(decodedJWT.payload)) {
 }
 ```
 
+### Checking if an access token is expired
+
+We offer a helper method to check whether an access token is expired. This is useful when you manage tokens yourself (instead of using `makeSalesChannel` / `makeIntegration`) and want to proactively refresh an expired token before sending an API request that is doomed to fail with a `401` status code.
+
+It accepts an optional `offsetSeconds` (defaults to `0`) to consider the token expired a few seconds ahead of time, as a clock-skew / in-flight request margin. It returns `true` for tokens that cannot be decoded.
+
+```ts
+import { jwtIsExpired } from "@commercelayer/js-auth"
+
+if (jwtIsExpired(accessToken, 30)) {
+  // refresh the token (the token is expired or will expire within 30 seconds)
+}
+```
+
 ### Verifying an access token
 
 We offer an helper method to verify an access token.