Storage

The SDK uses a pluggable StorageProvider to persist authentication tokens. By default, tokens live only in memory and are lost on page reload.

Default behavior

The SDK ships with a noopStorageProvider that does nothing:

const noopStorageProvider: StorageProvider = {
  getItem: async () => null,
  setItem: async () => {},
  removeItem: async () => {},
};

This means tokens are not persisted by default. You must configure a StorageProvider if you want tokens to survive page reloads or app restarts.

StorageProvider interface

type StorageProvider = {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
};

All methods are async to support server-side storage backends (cookies, databases, etc.).

Storage keys

The SDK uses two keys to store tokens:

Key	Value
heuristikAuth_accessToken	Access token
heuristikAuth_refreshToken	Refresh token

localStorage adapter

The simplest adapter wraps localStorage:

import { setStorageProvider } from '@heuristik/hhjssdk';

setStorageProvider({
  getItem: async (key) => localStorage.getItem(key),
  setItem: async (key, value) => localStorage.setItem(key, value),
  removeItem: async (key) => localStorage.removeItem(key),
});

warning

localStorage stores tokens as plain text accessible to any JavaScript on the page. This is suitable for development but not recommended for production.

Cookie-based adapter

For better security, use an HttpOnly cookie adapter that delegates to your server:

import { setStorageProvider } from '@heuristik/hhjssdk';

setStorageProvider({
  getItem: async (key) => {
    // Read from a non-HttpOnly cookie (or call your server)
    const match = document.cookie.match(new RegExp(`${key}=([^;]+)`));
    return match ? decodeURIComponent(match[1]) : null;
  },
  setItem: async (key, value) => {
    document.cookie = `${key}=${encodeURIComponent(value)}; path=/; SameSite=Strict`;
  },
  removeItem: async (key) => {
    document.cookie = `${key}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
  },
});

Production recommendation

In production, use HttpOnly cookies managed by your backend. The StorageProvider on the client should call server endpoints that set/read/clear HttpOnly cookies. This prevents XSS attacks from accessing tokens.

Setup order

Important

Call setStorageProvider() before creating the HeuristikClient. The provider is read when client.init() calls loadAuthTokens().

import { HeuristikClient, setStorageProvider } from '@heuristik/hhjssdk';

// 1. Configure storage FIRST
setStorageProvider({ /* ... */ });

// 2. Then create the client
const client = new HeuristikClient({ /* ... */ });

// 3. Init will load tokens from your provider
await client.init();

Error handling

Storage operations are wrapped in try/catch internally. If the provider throws, the SDK wraps it in an SDKError with the appropriate message:

Operation	Error message key
Save tokens	STORAGE_SAVE_TOKENS_FAILED
Load tokens	STORAGE_LOAD_TOKENS_FAILED
Clear tokens	STORAGE_CLEAR_TOKENS_FAILED