@wix/sdk 1.20.0 → 1.21.1

package/build/auth/SiteSessionAuth.d.ts

@@ -1,10 +1,32 @@
-import { RefreshToken, Tokens } from './oauth2/types.js';
+import { RefreshToken, Tokens, TokenStorage } from './oauth2/types.js';
 import { isVisitorCookieWarmedUp, preWarmVisitorCookie } from './pre-warm-cookie.js';
+/**
+ * Site session authentication strategy for Wix SDK.
+ * @param config - Configuration object
+ * @param config.clientId - The OAuth client ID
+ * @param config.publicKey - Optional public key for token verification
+ * @param config.tokens - Initial tokens for in-memory storage (mutually exclusive with `tokenStorage`)
+ * @param config.tokenStorage - Custom storage implementation (mutually exclusive with `tokens`).
+ *   When provided, the strategy delegates all token persistence to this storage.
+ *   The storage's `getTokens()` must always return `Tokens` (use `EMPTY_TOKENS` as fallback).
+ * @returns Site session auth instance
+ * @example
+ * // Default in-memory storage with initial tokens
+ * SiteSessionAuth({ clientId: 'xxx', tokens: myTokens })
+ * @example
+ * // Custom storage (e.g., cookies)
+ * SiteSessionAuth({ clientId: 'xxx', tokenStorage: myCookieStorage })
+ */
 export declare function SiteSessionAuth(config: {
     clientId: string;
     publicKey?: string;
+} & ({
     tokens?: Tokens;
-}): {
+    tokenStorage?: never;
+} | {
+    tokenStorage: TokenStorage;
+    tokens?: never;
+})): {
     generateVisitorTokens: (tokens?: Partial<Tokens>) => Promise<Tokens>;
     renewToken: (refreshToken: RefreshToken) => Promise<Tokens>;
     getAuthHeaders: () => Promise<{

package/build/auth/SiteSessionAuth.js

@@ -1,28 +1,56 @@
 import { biHeaderGenerator } from '../bi/biHeaderGenerator.js';
 import { DEFAULT_API_URL } from '../common.js';
 import { createAccessToken, isTokenExpired } from '../tokenHelpers.js';
-import { TokenRole } from './oauth2/types.js';
+import { TokenRole, } from './oauth2/types.js';
+import { EMPTY_TOKENS, createLocalTokenStorage, } from './oauth2/token-storage.js';
 import { isVisitorCookieWarmedUp, preWarmVisitorCookie, } from './pre-warm-cookie.js';
+/**
+ * Site session authentication strategy for Wix SDK.
+ * @param config - Configuration object
+ * @param config.clientId - The OAuth client ID
+ * @param config.publicKey - Optional public key for token verification
+ * @param config.tokens - Initial tokens for in-memory storage (mutually exclusive with `tokenStorage`)
+ * @param config.tokenStorage - Custom storage implementation (mutually exclusive with `tokens`).
+ *   When provided, the strategy delegates all token persistence to this storage.
+ *   The storage's `getTokens()` must always return `Tokens` (use `EMPTY_TOKENS` as fallback).
+ * @returns Site session auth instance
+ * @example
+ * // Default in-memory storage with initial tokens
+ * SiteSessionAuth({ clientId: 'xxx', tokens: myTokens })
+ * @example
+ * // Custom storage (e.g., cookies)
+ * SiteSessionAuth({ clientId: 'xxx', tokenStorage: myCookieStorage })
+ */
 export function SiteSessionAuth(config) {
-    const _tokens = config.tokens || {
-        accessToken: { value: '', expiresAt: 0 },
-        refreshToken: { value: '', role: TokenRole.NONE },
-    };
+    const _tokenStorage = config.tokenStorage ??
+        createLocalTokenStorage(config.tokens ?? EMPTY_TOKENS);
+    const getTokens = () => _tokenStorage.getTokens();
     const setTokens = (tokens) => {
-        _tokens.accessToken = tokens.accessToken;
-        _tokens.refreshToken = tokens.refreshToken;
+        _tokenStorage.setTokens(tokens);
     };
     const getAuthHeaders = async () => {
-        if (!_tokens.accessToken?.value || isTokenExpired(_tokens.accessToken)) {
-            const tokens = await generateVisitorTokens({
-                refreshToken: _tokens.refreshToken,
+        const currentTokens = getTokens();
+        if (!currentTokens.accessToken?.value ||
+            isTokenExpired(currentTokens.accessToken)) {
+            const newTokens = await generateVisitorTokens({
+                refreshToken: currentTokens.refreshToken,
             });
-            setTokens(tokens);
+            setTokens(newTokens);
         }
         return Promise.resolve({
-            headers: { Authorization: _tokens.accessToken.value },
+            headers: { Authorization: getTokens().accessToken.value },
         });
     };
+    /**
+     * Name is misleading, it should be called generateTokens. Ensures valid tokens are available, refreshing or generating new ones as needed.
+     *
+     * Scenarios:
+     * 1. If valid (non-expired) access and refresh tokens are provided, returns them as-is.
+     * 2. If a refresh token is provided but access token is missing/expired, attempts to renew using the refresh token.
+     * 3. If renewal fails or no refresh token exists, generates new anonymous visitor tokens.
+     * @param tokens - Optional partial tokens (accessToken and/or refreshToken)
+     * @returns Valid tokens (accessToken + refreshToken)
+     */
     const generateVisitorTokens = async (tokens) => {
         if (tokens?.accessToken?.value &&
             tokens?.refreshToken?.value &&
@@ -62,7 +90,7 @@ export function SiteSessionAuth(config) {
         };
     };
     const loggedIn = () => {
-        return _tokens.refreshToken.role === TokenRole.MEMBER;
+        return getTokens().refreshToken.role === TokenRole.MEMBER;
     };
     return {
         generateVisitorTokens,
@@ -70,7 +98,7 @@ export function SiteSessionAuth(config) {
         getAuthHeaders,
         setTokens,
         loggedIn,
-        getTokens: () => _tokens,
+        getTokens,
         isSessionSynced: isVisitorCookieWarmedUp,
         syncToWixPages: preWarmVisitorCookie,
         shouldUseCDN: true,

package/build/auth/oauth2/OAuthStrategy.d.ts

@@ -1,9 +1,31 @@
-import { IOAuthStrategy, Tokens } from './types.js';
+import { IOAuthStrategy, Tokens, TokenStorage } from './types.js';
+/**
+ * OAuth authentication strategy for Wix SDK.
+ * @param config - Configuration object
+ * @param config.clientId - The OAuth client ID
+ * @param config.publicKey - Optional public key for token verification
+ * @param config.tokens - Initial tokens for in-memory storage (mutually exclusive with `tokenStorage`)
+ * @param config.tokenStorage - Custom storage implementation (mutually exclusive with `tokens`).
+ *   When provided, the strategy delegates all token persistence to this storage.
+ *   The storage's `getTokens()` must always return `Tokens` (use `EMPTY_TOKENS` as fallback).
+ * @returns OAuth strategy instance
+ * @example
+ * // Default in-memory storage with initial tokens
+ * OAuthStrategy({ clientId: 'xxx', tokens: myTokens })
+ * @example
+ * // Custom storage (e.g., cookies)
+ * OAuthStrategy({ clientId: 'xxx', tokenStorage: myCookieStorage })
+ */
 export declare function OAuthStrategy(config: {
     clientId: string;
     publicKey?: string;
+} & ({
     tokens?: Tokens;
-}): IOAuthStrategy;
+    tokenStorage?: never;
+} | {
+    tokenStorage: TokenStorage;
+    tokens?: never;
+})): IOAuthStrategy;
 export interface TokenResponse {
     access_token: string;
     expires_in: number;

package/build/auth/oauth2/OAuthStrategy.js

@@ -9,34 +9,60 @@ import { EMAIL_EXISTS, INVALID_CAPTCHA, INVALID_PASSWORD, MISSING_CAPTCHA, RESET
 import { biHeaderGenerator } from '../../bi/biHeaderGenerator.js';
 import { pkceChallenge } from './pkce-challenge.js';
 import { isVisitorCookieWarmedUp, preWarmVisitorCookie, } from '../pre-warm-cookie.js';
+import { EMPTY_TOKENS, createLocalTokenStorage } from './token-storage.js';
 const moduleWithTokens = { redirects, authentication, recovery, verification };
+/**
+ * OAuth authentication strategy for Wix SDK.
+ * @param config - Configuration object
+ * @param config.clientId - The OAuth client ID
+ * @param config.publicKey - Optional public key for token verification
+ * @param config.tokens - Initial tokens for in-memory storage (mutually exclusive with `tokenStorage`)
+ * @param config.tokenStorage - Custom storage implementation (mutually exclusive with `tokens`).
+ *   When provided, the strategy delegates all token persistence to this storage.
+ *   The storage's `getTokens()` must always return `Tokens` (use `EMPTY_TOKENS` as fallback).
+ * @returns OAuth strategy instance
+ * @example
+ * // Default in-memory storage with initial tokens
+ * OAuthStrategy({ clientId: 'xxx', tokens: myTokens })
+ * @example
+ * // Custom storage (e.g., cookies)
+ * OAuthStrategy({ clientId: 'xxx', tokenStorage: myCookieStorage })
+ */
 export function OAuthStrategy(config) {
-    const _tokens = config.tokens || {
-        accessToken: { value: '', expiresAt: 0 },
-        refreshToken: { value: '', role: TokenRole.NONE },
-    };
-    const setTokens = (tokens) => {
-        _tokens.accessToken = tokens.accessToken;
-        _tokens.refreshToken = tokens.refreshToken;
-    };
+    const _tokenStorage = config.tokenStorage ??
+        createLocalTokenStorage(config.tokens ?? EMPTY_TOKENS);
+    const getTokens = () => _tokenStorage.getTokens();
+    const setTokens = (tokens) => _tokenStorage.setTokens(tokens);
     let _state = {
         loginState: LoginState.INITIAL,
     };
     const getAuthHeaders = async () => {
-        if (!_tokens.accessToken?.value || isTokenExpired(_tokens.accessToken)) {
-            const tokens = await generateVisitorTokens({
-                refreshToken: _tokens.refreshToken,
+        const currentTokens = getTokens();
+        if (!currentTokens.accessToken?.value ||
+            isTokenExpired(currentTokens.accessToken)) {
+            const newTokens = await generateVisitorTokens({
+                refreshToken: currentTokens.refreshToken,
             });
-            setTokens(tokens);
+            setTokens(newTokens);
         }
         return Promise.resolve({
-            headers: { Authorization: _tokens.accessToken.value },
+            headers: { Authorization: getTokens().accessToken.value },
         });
     };
     const wixClientWithTokens = createClient({
         modules: moduleWithTokens,
         auth: { getAuthHeaders },
     });
+    /**
+     * Name is misleading, it should be called generateTokens. Ensures valid tokens are available, refreshing or generating new ones as needed.
+     *
+     * Scenarios:
+     * 1. If valid (non-expired) access and refresh tokens are provided, returns them as-is.
+     * 2. If a refresh token is provided but access token is missing/expired, attempts to renew using the refresh token.
+     * 3. If renewal fails or no refresh token exists, generates new anonymous visitor tokens.
+     * @param tokens - Optional partial tokens (accessToken and/or refreshToken)
+     * @returns Valid tokens (accessToken + refreshToken)
+     */
     const generateVisitorTokens = async (tokens) => {
         if (tokens?.accessToken?.value &&
             tokens?.refreshToken?.value &&
@@ -165,8 +191,10 @@ export function OAuthStrategy(config) {
                 postFlowUrl: originalUrl,
             },
         });
-        _tokens.accessToken = { value: '', expiresAt: 0 };
-        _tokens.refreshToken = { value: '', role: TokenRole.NONE };
+        setTokens({
+            accessToken: { value: '', expiresAt: 0 },
+            refreshToken: { value: '', role: TokenRole.NONE },
+        });
         return { logoutUrl: redirectSession.fullUrl };
     };
     const handleState = (response) => {
@@ -313,7 +341,7 @@ export function OAuthStrategy(config) {
         });
     };
     const loggedIn = () => {
-        return _tokens.refreshToken.role === TokenRole.MEMBER;
+        return getTokens().refreshToken.role === TokenRole.MEMBER;
     };
     const getMemberTokensForExternalLogin = async (memberId, apiKey) => {
         const tokensResponse = await fetchTokens({
@@ -321,7 +349,7 @@ export function OAuthStrategy(config) {
             scope: 'offline_access',
             member_id: memberId,
         }, {
-            Authorization: _tokens.accessToken.value + ',' + apiKey,
+            Authorization: getTokens().accessToken.value + ',' + apiKey,
         });
         return {
             accessToken: createAccessToken(tokensResponse.access_token, tokensResponse.expires_in),
@@ -340,7 +368,7 @@ export function OAuthStrategy(config) {
         generateOAuthData,
         getAuthHeaders,
         setTokens,
-        getTokens: () => _tokens,
+        getTokens,
         loggedIn,
         logout,
         register,

package/build/auth/oauth2/token-storage.d.ts

@@ -0,0 +1,3 @@
+import { type TokenStorage, type Tokens } from './types.js';
+export declare const EMPTY_TOKENS: Tokens;
+export declare function createLocalTokenStorage(initialTokens: Tokens): TokenStorage;

package/build/auth/oauth2/token-storage.js

@@ -0,0 +1,15 @@
+import { TokenRole } from './types.js';
+// These tokens are considered empty tokens, and can be used as a fallback when no tokens are available.
+export const EMPTY_TOKENS = {
+    accessToken: { value: '', expiresAt: 0 },
+    refreshToken: { value: '', role: TokenRole.NONE },
+};
+export function createLocalTokenStorage(initialTokens) {
+    let _tokens = initialTokens;
+    return {
+        getTokens: () => _tokens,
+        setTokens: (tokens) => {
+            _tokens = tokens;
+        },
+    };
+}

package/build/auth/oauth2/types.d.ts

@@ -4,6 +4,14 @@ export interface Tokens {
     accessToken: AccessToken;
     refreshToken: RefreshToken;
 }
+/**
+ * Interface for custom token storage implementations.
+ * Storage must always return valid Tokens - use EMPTY_TOKENS as fallback when underlying storage is empty.
+ */
+export interface TokenStorage {
+    getTokens(): Tokens;
+    setTokens(tokens: Tokens): void;
+}
 export interface Token {
     value: string;
 }

package/build/index.d.ts

@@ -2,6 +2,7 @@ export * from './wixClient.js';
 export * from './wixMedia.js';
 export * from './auth/oauth2/OAuthStrategy.js';
 export * from './auth/oauth2/types.js';
+export * from './auth/oauth2/token-storage.js';
 export * from './auth/ApiKeyAuthStrategy.js';
 export * from './auth/AppStrategy.js';
 export * from '@wix/sdk-types';

package/build/index.js

@@ -2,6 +2,7 @@ export * from './wixClient.js';
 export * from './wixMedia.js';
 export * from './auth/oauth2/OAuthStrategy.js';
 export * from './auth/oauth2/types.js';
+export * from './auth/oauth2/token-storage.js';
 export * from './auth/ApiKeyAuthStrategy.js';
 export * from './auth/AppStrategy.js';
 export * from '@wix/sdk-types';

package/cjs/build/auth/SiteSessionAuth.d.ts

@@ -1,10 +1,32 @@
-import { RefreshToken, Tokens } from './oauth2/types.js';
+import { RefreshToken, Tokens, TokenStorage } from './oauth2/types.js';
 import { isVisitorCookieWarmedUp, preWarmVisitorCookie } from './pre-warm-cookie.js';
+/**
+ * Site session authentication strategy for Wix SDK.
+ * @param config - Configuration object
+ * @param config.clientId - The OAuth client ID
+ * @param config.publicKey - Optional public key for token verification
+ * @param config.tokens - Initial tokens for in-memory storage (mutually exclusive with `tokenStorage`)
+ * @param config.tokenStorage - Custom storage implementation (mutually exclusive with `tokens`).
+ *   When provided, the strategy delegates all token persistence to this storage.
+ *   The storage's `getTokens()` must always return `Tokens` (use `EMPTY_TOKENS` as fallback).
+ * @returns Site session auth instance
+ * @example
+ * // Default in-memory storage with initial tokens
+ * SiteSessionAuth({ clientId: 'xxx', tokens: myTokens })
+ * @example
+ * // Custom storage (e.g., cookies)
+ * SiteSessionAuth({ clientId: 'xxx', tokenStorage: myCookieStorage })
+ */
 export declare function SiteSessionAuth(config: {
     clientId: string;
     publicKey?: string;
+} & ({
     tokens?: Tokens;
-}): {
+    tokenStorage?: never;
+} | {
+    tokenStorage: TokenStorage;
+    tokens?: never;
+})): {
     generateVisitorTokens: (tokens?: Partial<Tokens>) => Promise<Tokens>;
     renewToken: (refreshToken: RefreshToken) => Promise<Tokens>;
     getAuthHeaders: () => Promise<{

package/cjs/build/auth/SiteSessionAuth.js

@@ -5,27 +5,55 @@ const biHeaderGenerator_js_1 = require("../bi/biHeaderGenerator.js");
 const common_js_1 = require("../common.js");
 const tokenHelpers_js_1 = require("../tokenHelpers.js");
 const types_js_1 = require("./oauth2/types.js");
+const token_storage_js_1 = require("./oauth2/token-storage.js");
 const pre_warm_cookie_js_1 = require("./pre-warm-cookie.js");
+/**
+ * Site session authentication strategy for Wix SDK.
+ * @param config - Configuration object
+ * @param config.clientId - The OAuth client ID
+ * @param config.publicKey - Optional public key for token verification
+ * @param config.tokens - Initial tokens for in-memory storage (mutually exclusive with `tokenStorage`)
+ * @param config.tokenStorage - Custom storage implementation (mutually exclusive with `tokens`).
+ *   When provided, the strategy delegates all token persistence to this storage.
+ *   The storage's `getTokens()` must always return `Tokens` (use `EMPTY_TOKENS` as fallback).
+ * @returns Site session auth instance
+ * @example
+ * // Default in-memory storage with initial tokens
+ * SiteSessionAuth({ clientId: 'xxx', tokens: myTokens })
+ * @example
+ * // Custom storage (e.g., cookies)
+ * SiteSessionAuth({ clientId: 'xxx', tokenStorage: myCookieStorage })
+ */
 function SiteSessionAuth(config) {
-    const _tokens = config.tokens || {
-        accessToken: { value: '', expiresAt: 0 },
-        refreshToken: { value: '', role: types_js_1.TokenRole.NONE },
-    };
+    const _tokenStorage = config.tokenStorage ??
+        (0, token_storage_js_1.createLocalTokenStorage)(config.tokens ?? token_storage_js_1.EMPTY_TOKENS);
+    const getTokens = () => _tokenStorage.getTokens();
     const setTokens = (tokens) => {
-        _tokens.accessToken = tokens.accessToken;
-        _tokens.refreshToken = tokens.refreshToken;
+        _tokenStorage.setTokens(tokens);
     };
     const getAuthHeaders = async () => {
-        if (!_tokens.accessToken?.value || (0, tokenHelpers_js_1.isTokenExpired)(_tokens.accessToken)) {
-            const tokens = await generateVisitorTokens({
-                refreshToken: _tokens.refreshToken,
+        const currentTokens = getTokens();
+        if (!currentTokens.accessToken?.value ||
+            (0, tokenHelpers_js_1.isTokenExpired)(currentTokens.accessToken)) {
+            const newTokens = await generateVisitorTokens({
+                refreshToken: currentTokens.refreshToken,
             });
-            setTokens(tokens);
+            setTokens(newTokens);
         }
         return Promise.resolve({
-            headers: { Authorization: _tokens.accessToken.value },
+            headers: { Authorization: getTokens().accessToken.value },
         });
     };
+    /**
+     * Name is misleading, it should be called generateTokens. Ensures valid tokens are available, refreshing or generating new ones as needed.
+     *
+     * Scenarios:
+     * 1. If valid (non-expired) access and refresh tokens are provided, returns them as-is.
+     * 2. If a refresh token is provided but access token is missing/expired, attempts to renew using the refresh token.
+     * 3. If renewal fails or no refresh token exists, generates new anonymous visitor tokens.
+     * @param tokens - Optional partial tokens (accessToken and/or refreshToken)
+     * @returns Valid tokens (accessToken + refreshToken)
+     */
     const generateVisitorTokens = async (tokens) => {
         if (tokens?.accessToken?.value &&
             tokens?.refreshToken?.value &&
@@ -65,7 +93,7 @@ function SiteSessionAuth(config) {
         };
     };
     const loggedIn = () => {
-        return _tokens.refreshToken.role === types_js_1.TokenRole.MEMBER;
+        return getTokens().refreshToken.role === types_js_1.TokenRole.MEMBER;
     };
     return {
         generateVisitorTokens,
@@ -73,7 +101,7 @@ function SiteSessionAuth(config) {
         getAuthHeaders,
         setTokens,
         loggedIn,
-        getTokens: () => _tokens,
+        getTokens,
         isSessionSynced: pre_warm_cookie_js_1.isVisitorCookieWarmedUp,
         syncToWixPages: pre_warm_cookie_js_1.preWarmVisitorCookie,
         shouldUseCDN: true,

package/cjs/build/auth/oauth2/OAuthStrategy.d.ts

@@ -1,9 +1,31 @@
-import { IOAuthStrategy, Tokens } from './types.js';
+import { IOAuthStrategy, Tokens, TokenStorage } from './types.js';
+/**
+ * OAuth authentication strategy for Wix SDK.
+ * @param config - Configuration object
+ * @param config.clientId - The OAuth client ID
+ * @param config.publicKey - Optional public key for token verification
+ * @param config.tokens - Initial tokens for in-memory storage (mutually exclusive with `tokenStorage`)
+ * @param config.tokenStorage - Custom storage implementation (mutually exclusive with `tokens`).
+ *   When provided, the strategy delegates all token persistence to this storage.
+ *   The storage's `getTokens()` must always return `Tokens` (use `EMPTY_TOKENS` as fallback).
+ * @returns OAuth strategy instance
+ * @example
+ * // Default in-memory storage with initial tokens
+ * OAuthStrategy({ clientId: 'xxx', tokens: myTokens })
+ * @example
+ * // Custom storage (e.g., cookies)
+ * OAuthStrategy({ clientId: 'xxx', tokenStorage: myCookieStorage })
+ */
 export declare function OAuthStrategy(config: {
     clientId: string;
     publicKey?: string;
+} & ({
     tokens?: Tokens;
-}): IOAuthStrategy;
+    tokenStorage?: never;
+} | {
+    tokenStorage: TokenStorage;
+    tokens?: never;
+})): IOAuthStrategy;
 export interface TokenResponse {
     access_token: string;
     expires_in: number;

package/cjs/build/auth/oauth2/OAuthStrategy.js

@@ -12,34 +12,60 @@ const constants_js_1 = require("./constants.js");
 const biHeaderGenerator_js_1 = require("../../bi/biHeaderGenerator.js");
 const pkce_challenge_js_1 = require("./pkce-challenge.js");
 const pre_warm_cookie_js_1 = require("../pre-warm-cookie.js");
+const token_storage_js_1 = require("./token-storage.js");
 const moduleWithTokens = { redirects: redirects_1.redirects, authentication: identity_1.authentication, recovery: identity_1.recovery, verification: identity_1.verification };
+/**
+ * OAuth authentication strategy for Wix SDK.
+ * @param config - Configuration object
+ * @param config.clientId - The OAuth client ID
+ * @param config.publicKey - Optional public key for token verification
+ * @param config.tokens - Initial tokens for in-memory storage (mutually exclusive with `tokenStorage`)
+ * @param config.tokenStorage - Custom storage implementation (mutually exclusive with `tokens`).
+ *   When provided, the strategy delegates all token persistence to this storage.
+ *   The storage's `getTokens()` must always return `Tokens` (use `EMPTY_TOKENS` as fallback).
+ * @returns OAuth strategy instance
+ * @example
+ * // Default in-memory storage with initial tokens
+ * OAuthStrategy({ clientId: 'xxx', tokens: myTokens })
+ * @example
+ * // Custom storage (e.g., cookies)
+ * OAuthStrategy({ clientId: 'xxx', tokenStorage: myCookieStorage })
+ */
 function OAuthStrategy(config) {
-    const _tokens = config.tokens || {
-        accessToken: { value: '', expiresAt: 0 },
-        refreshToken: { value: '', role: types_js_1.TokenRole.NONE },
-    };
-    const setTokens = (tokens) => {
-        _tokens.accessToken = tokens.accessToken;
-        _tokens.refreshToken = tokens.refreshToken;
-    };
+    const _tokenStorage = config.tokenStorage ??
+        (0, token_storage_js_1.createLocalTokenStorage)(config.tokens ?? token_storage_js_1.EMPTY_TOKENS);
+    const getTokens = () => _tokenStorage.getTokens();
+    const setTokens = (tokens) => _tokenStorage.setTokens(tokens);
     let _state = {
         loginState: types_js_1.LoginState.INITIAL,
     };
     const getAuthHeaders = async () => {
-        if (!_tokens.accessToken?.value || (0, tokenHelpers_js_1.isTokenExpired)(_tokens.accessToken)) {
-            const tokens = await generateVisitorTokens({
-                refreshToken: _tokens.refreshToken,
+        const currentTokens = getTokens();
+        if (!currentTokens.accessToken?.value ||
+            (0, tokenHelpers_js_1.isTokenExpired)(currentTokens.accessToken)) {
+            const newTokens = await generateVisitorTokens({
+                refreshToken: currentTokens.refreshToken,
             });
-            setTokens(tokens);
+            setTokens(newTokens);
         }
         return Promise.resolve({
-            headers: { Authorization: _tokens.accessToken.value },
+            headers: { Authorization: getTokens().accessToken.value },
         });
     };
     const wixClientWithTokens = (0, wixClient_js_1.createClient)({
         modules: moduleWithTokens,
         auth: { getAuthHeaders },
     });
+    /**
+     * Name is misleading, it should be called generateTokens. Ensures valid tokens are available, refreshing or generating new ones as needed.
+     *
+     * Scenarios:
+     * 1. If valid (non-expired) access and refresh tokens are provided, returns them as-is.
+     * 2. If a refresh token is provided but access token is missing/expired, attempts to renew using the refresh token.
+     * 3. If renewal fails or no refresh token exists, generates new anonymous visitor tokens.
+     * @param tokens - Optional partial tokens (accessToken and/or refreshToken)
+     * @returns Valid tokens (accessToken + refreshToken)
+     */
     const generateVisitorTokens = async (tokens) => {
         if (tokens?.accessToken?.value &&
             tokens?.refreshToken?.value &&
@@ -168,8 +194,10 @@ function OAuthStrategy(config) {
                 postFlowUrl: originalUrl,
             },
         });
-        _tokens.accessToken = { value: '', expiresAt: 0 };
-        _tokens.refreshToken = { value: '', role: types_js_1.TokenRole.NONE };
+        setTokens({
+            accessToken: { value: '', expiresAt: 0 },
+            refreshToken: { value: '', role: types_js_1.TokenRole.NONE },
+        });
         return { logoutUrl: redirectSession.fullUrl };
     };
     const handleState = (response) => {
@@ -316,7 +344,7 @@ function OAuthStrategy(config) {
         });
     };
     const loggedIn = () => {
-        return _tokens.refreshToken.role === types_js_1.TokenRole.MEMBER;
+        return getTokens().refreshToken.role === types_js_1.TokenRole.MEMBER;
     };
     const getMemberTokensForExternalLogin = async (memberId, apiKey) => {
         const tokensResponse = await fetchTokens({
@@ -324,7 +352,7 @@ function OAuthStrategy(config) {
             scope: 'offline_access',
             member_id: memberId,
         }, {
-            Authorization: _tokens.accessToken.value + ',' + apiKey,
+            Authorization: getTokens().accessToken.value + ',' + apiKey,
         });
         return {
             accessToken: (0, tokenHelpers_js_1.createAccessToken)(tokensResponse.access_token, tokensResponse.expires_in),
@@ -343,7 +371,7 @@ function OAuthStrategy(config) {
         generateOAuthData,
         getAuthHeaders,
         setTokens,
-        getTokens: () => _tokens,
+        getTokens,
         loggedIn,
         logout,
         register,

package/cjs/build/auth/oauth2/token-storage.d.ts

@@ -0,0 +1,3 @@
+import { type TokenStorage, type Tokens } from './types.js';
+export declare const EMPTY_TOKENS: Tokens;
+export declare function createLocalTokenStorage(initialTokens: Tokens): TokenStorage;

package/cjs/build/auth/oauth2/token-storage.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_TOKENS = void 0;
+exports.createLocalTokenStorage = createLocalTokenStorage;
+const types_js_1 = require("./types.js");
+// These tokens are considered empty tokens, and can be used as a fallback when no tokens are available.
+exports.EMPTY_TOKENS = {
+    accessToken: { value: '', expiresAt: 0 },
+    refreshToken: { value: '', role: types_js_1.TokenRole.NONE },
+};
+function createLocalTokenStorage(initialTokens) {
+    let _tokens = initialTokens;
+    return {
+        getTokens: () => _tokens,
+        setTokens: (tokens) => {
+            _tokens = tokens;
+        },
+    };
+}

package/cjs/build/auth/oauth2/types.d.ts

@@ -4,6 +4,14 @@ export interface Tokens {
     accessToken: AccessToken;
     refreshToken: RefreshToken;
 }
+/**
+ * Interface for custom token storage implementations.
+ * Storage must always return valid Tokens - use EMPTY_TOKENS as fallback when underlying storage is empty.
+ */
+export interface TokenStorage {
+    getTokens(): Tokens;
+    setTokens(tokens: Tokens): void;
+}
 export interface Token {
     value: string;
 }

package/cjs/build/index.d.ts

@@ -2,6 +2,7 @@ export * from './wixClient.js';
 export * from './wixMedia.js';
 export * from './auth/oauth2/OAuthStrategy.js';
 export * from './auth/oauth2/types.js';
+export * from './auth/oauth2/token-storage.js';
 export * from './auth/ApiKeyAuthStrategy.js';
 export * from './auth/AppStrategy.js';
 export * from '@wix/sdk-types';

package/cjs/build/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./wixClient.js"), exports);
 __exportStar(require("./wixMedia.js"), exports);
 __exportStar(require("./auth/oauth2/OAuthStrategy.js"), exports);
 __exportStar(require("./auth/oauth2/types.js"), exports);
+__exportStar(require("./auth/oauth2/token-storage.js"), exports);
 __exportStar(require("./auth/ApiKeyAuthStrategy.js"), exports);
 __exportStar(require("./auth/AppStrategy.js"), exports);
 __exportStar(require("@wix/sdk-types"), exports);

package/package.json

@@ -1,14 +1,42 @@
 {
   "name": "@wix/sdk",
-  "version": "1.20.0",
-  "license": "MIT",
+  "version": "1.21.1",
   "author": {
     "name": "Ronny Ringel",
     "email": "ronnyr@wix.com"
   },
-  "main": "cjs/build/index.js",
-  "module": "build/index.mjs",
-  "type": "module",
+  "dependencies": {
+    "@wix/identity": "^1.0.104",
+    "@wix/image-kit": "^1.114.0",
+    "@wix/redirects": "^1.0.70",
+    "@wix/sdk-context": "0.0.1",
+    "@wix/sdk-runtime": "1.0.3",
+    "@wix/sdk-types": "1.17.1",
+    "jose": "^5.10.0",
+    "type-fest": "^4.41.0"
+  },
+  "devDependencies": {
+    "@types/is-ci": "^3.0.4",
+    "@types/node": "^20.19.25",
+    "@vitest/ui": "^1.6.1",
+    "@wix/ecom": "^1.0.886",
+    "@wix/events": "^1.0.382",
+    "@wix/metro": "^1.0.93",
+    "@wix/metro-runtime": "^1.1891.0",
+    "@wix/sdk-runtime": "1.0.3",
+    "eslint": "^8.57.1",
+    "eslint-config-sdk": "1.0.0",
+    "graphql": "^16.8.0",
+    "is-ci": "^3.0.1",
+    "jsdom": "^22.1.0",
+    "msw": "^2.12.2",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1",
+    "vitest-teamcity-reporter": "^0.3.1"
+  },
+  "eslintConfig": {
+    "extends": "sdk"
+  },
   "exports": {
     ".": {
       "import": "./build/index.js",
@@ -48,7 +76,6 @@
       "require": "./cjs/build/media/helpers.js"
     }
   },
-  "sideEffects": false,
   "files": [
     "build",
     "auth",
@@ -57,57 +84,30 @@
     "context",
     "media"
   ],
+  "license": "MIT",
+  "lint-staged": {
+    "*.{js,ts}": "yarn lint"
+  },
+  "main": "cjs/build/index.js",
+  "module": "build/index.mjs",
+  "optionalDependencies": {
+    "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "scripts": {
     "build": "tsc && tsc --project tsconfig.cjs.json",
-    "test": "vitest run",
     "lint": "eslint --max-warnings=0 .",
     "lint:fix": "eslint --max-warnings=0 . --fix",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
-  "lint-staged": {
-    "*.{js,ts}": "yarn lint"
-  },
-  "dependencies": {
-    "@wix/identity": "^1.0.104",
-    "@wix/image-kit": "^1.114.0",
-    "@wix/redirects": "^1.0.70",
-    "@wix/sdk-context": "0.0.1",
-    "@wix/sdk-runtime": "1.0.2",
-    "@wix/sdk-types": "1.16.0",
-    "jose": "^5.10.0",
-    "type-fest": "^4.41.0"
-  },
-  "optionalDependencies": {
-    "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0"
-  },
-  "devDependencies": {
-    "@types/is-ci": "^3.0.4",
-    "@types/node": "^20.19.25",
-    "@vitest/ui": "^1.6.1",
-    "@wix/ecom": "^1.0.886",
-    "@wix/events": "^1.0.382",
-    "@wix/metro": "^1.0.93",
-    "@wix/metro-runtime": "^1.1891.0",
-    "@wix/sdk-runtime": "1.0.2",
-    "eslint": "^8.57.1",
-    "eslint-config-sdk": "1.0.0",
-    "graphql": "^16.8.0",
-    "is-ci": "^3.0.1",
-    "jsdom": "^22.1.0",
-    "msw": "^2.12.2",
-    "typescript": "^5.9.3",
-    "vitest": "^1.6.1",
-    "vitest-teamcity-reporter": "^0.3.1"
-  },
-  "yoshiFlowLibrary": {
-    "buildEsmWithBabel": true
-  },
-  "eslintConfig": {
-    "extends": "sdk"
+  "sideEffects": false,
+  "type": "module",
+  "wallaby": {
+    "autoDetect": true
   },
   "wix": {
     "artifact": {
@@ -123,8 +123,8 @@
       ]
     }
   },
-  "wallaby": {
-    "autoDetect": true
+  "yoshiFlowLibrary": {
+    "buildEsmWithBabel": true
   },
-  "falconPackageHash": "4073f5e283bbe708a3e8e45d798f3998874111ad3aab43d426686c29"
+  "falconPackageHash": "b15d34d496e485b7ec7be4a51298d0acccc5273ecb15b7b370d50b9b"
 }