@fluid-app/storage-manager/README.md

Storage management utilities for Fluid Commerce applications

# @fluid-app/storage-manager

A utility package for Fluid Commerce applications that provides a consistent interface for working with browser storage (localStorage) and cookies. This package handles storage across browser environments including server-side rendering.

## Installation

```bash
npm install @fluid-app/storage-manager
# or
yarn add @fluid-app/storage-manager
# or
pnpm add @fluid-app/storage-manager
```

## Basic Usage

```typescript
import { STORAGE_KEYS, StorageManager } from "@fluid-app/storage-manager";

// Create a storage manager instance
const storageManager = new StorageManager();

// Store string data
storageManager.setItem(STORAGE_KEYS.CART, "cart_abc123");

// Retrieve string data
const cartToken = storageManager.getItem(STORAGE_KEYS.CART); // "cart_abc123"

// Store complex data (automatically serialized to JSON)
storageManager.setObject(STORAGE_KEYS.CART, {
  cart_token: "cart_abc123",
  items: [
    { id: 1, variant_id: 11601, quantity: 2 },
    { id: 2, variant_id: 11602, quantity: 1 },
  ],
  subtotal: "29.99",
});

// Retrieve complex data (automatically parsed from JSON)
const cart = storageManager.getObject(STORAGE_KEYS.CART);
console.log(cart.items.length); // 2

// Remove data
storageManager.removeItem(STORAGE_KEYS.CART);
```

## Working with Cookies

```typescript
import { COOKIE_KEYS, getCookie } from "@fluid-app/storage-manager";
import { getCountryFromLocale } from "path/to/localeUtils";

// Read a cookie value
const countryCookie = getCookie(COOKIE_KEYS.COUNTRY); // "US"

// The storage manager can also retrieve values from cookies as fallback
const storageManager = new StorageManager();

// Get country code with fallback to cookies
const locale = storageManager.getItem(STORAGE_KEYS.LOCALE);
const countryCode = getCountryFromLocale(locale);

// Get locale with fallback to cookies
const locale = storageManager.getItem(STORAGE_KEYS.LOCALE);
```

## Integration with Fluid Ecosystem

The Storage Manager is used by other Fluid packages to store:

1. **Cart data** (@fluid-app/fluid)
2. **Session tokens** (@fluid-app/fairshare)
3. **Fingerprint data** (@fluid-app/fairshare)
4. **Event queues** (@fluid-app/fairshare)

Example integration with Fluid SDK:

```typescript
import { initializeFluid } from "@fluid-app/fluid";

// Initialize Fluid SDK
initializeFluid({
  fluidShop: "your-shop-id",
  // Attribution is now handled server-side via the settings API
});

// You can still access other stored data if needed
const storageManager = new StorageManager();
const cartData = storageManager.getObject(STORAGE_KEYS.CART);
console.log("Current cart:", cartData);
```

## Storage Keys Reference

The package includes predefined storage keys for consistency:

```typescript
const STORAGE_KEYS = {
  ATTRIBUTION: "fs_attribution", // Attribution data
  ATTRIBUTION_CACHE: "fs_attribution_cache", // Cached attribution data
  CART: "fs_cart", // Cart data
  CLIENT_SETTINGS: "fs_client_settings",
  CONFIG: "fs_config", // SDK configuration
  COUNTRY: "fs_country", // Country code
  EVENT_QUEUE: "fs_event_queue", // Queued analytics events
  FINGERPRINT: "fs_fingerprint", // Browser fingerprint
  LOCALE: "fs_locale", // Locale
  SERVER_SETTINGS: "fs_server_settings", // Server settings
  SESSION: "fs_session", // Session token
  USER_ID: "fs_user_id", // User ID for identified users
};
```

## Cookie Keys Reference

The package includes predefined cookie keys:

```typescript
const COOKIE_KEYS = {
  COUNTRY: "country", // Country code cookie (often set by Cloudflare)
  LOCALE: "locale", // Locale cookie
};
```

## API Reference

### StorageManager Class

```typescript
class StorageManager {
  // Store string data
  setItem(key: string, value: string): void;

  // Retrieve string data
  getItem(key: string): string | null;

  // Remove data
  removeItem(key: string): void;

  // Store complex data (automatically serialized to JSON)
  setObject<T>(key: string, value: T): void;

  // Retrieve complex data (automatically parsed from JSON)
  getObject<T>(key: string): T | null;

  // Get country code from storage or cookies
  getCountryCode(): string;

  // Set country code
  setCountryCode(countryCode: string): void;

  // Get locale from storage or cookies
  getLocale(): string | null;

  // Set locale
  setLocale(locale: string): void;
}
```

### Utility Functions

```typescript
// Check if code is running in a browser environment
function isBrowser(): boolean;

// Get a cookie value by name
function getCookie(name: string): string | null;
```

## Server-Side Rendering Compatibility

This package safely handles both browser and server environments, making it compatible with frameworks like Next.js:

```typescript
// In a Next.js component (works in both client and server components)
import { StorageManager } from "@fluid-app/storage-manager";

export default function CartIndicator() {
  // Create a client component that uses localStorage safely
  "use client";

  const [itemCount, setItemCount] = useState(0);

  useEffect(() => {
    const storageManager = new StorageManager();
    const cart = storageManager.getObject("fs_cart");
    setItemCount(cart?.items?.length || 0);
  }, []);

  return <div>Cart Items: {itemCount}</div>;
}
```

## License

MIT