@wral/lib-user-facts

A lightweight client library for working with WRAL User Facts in browser-based applications.

This library provides an instance-scoped facade over the User Facts API with:

• Automatic authentication using @wral/sdk-auth-audience
• In-memory and localStorage caching with configurable TTLs
• Optimistic updates for create/update/delete operations
• SSR-safe initialization
• A simple, promise-based API

Installation

npm install @wral/lib-user-facts

Note: This package assumes your application already uses WRAL authentication and that @wral/sdk-auth-audience is properly configured.

Basic Usage

import { createClient } from "@wral/lib-user-facts";

const userFacts = createClient();

// Fetch all facts
const facts = await userFacts.getUserFacts();

// Fetch a single fact
const marketingOptIn = await userFacts.getUserFact("marketing_opt_in");

// Update a fact
await userFacts.updateUserFact("marketing_opt_in", true);

// Delete a fact
await userFacts.deleteUserFact("marketing_opt_in");

How It Works

Each call to createClient() returns an instance-scoped facade with its own:

• API client
• In-memory cache
• Persistence state
• Token lifecycle

This makes it safe to use multiple instances with different configurations if needed.

Authentication

Authentication is handled automatically:

• Uses the WRAL ID token from @wral/sdk-auth-audience
• Forces a token refresh if none is present
• Recreates the API client when the token changes

You do not need to manually pass credentials.

Caching Strategy

The library uses a two-tier cache:

1. In-memory cache

• Default TTL: 5 minutes
• Fastest access
• Cleared on page reload

2. Persistent cache (localStorage)

• Default TTL: 24 hours
• Survives reloads
• Automatically invalidated when expired

Cached data is transparently refreshed when stale.

Configuration

You can customize behavior when creating a client:

const userFacts = createClient({
  baseUrl: "https://api.wral.com/dev/user-facts/v1/",
  storageKey: "wral_user_facts",
  localTtlMs: 24 * 60 * 60 * 1000, // 24 hours
  memoryTtlMs: 5 * 60 * 1000,     // 5 minutes
  storage: window.localStorage,
  debug: true,
  logger: (level, ...args) => {
    console[level](...args);
  },
});

Configuration Options

| Option | Description | Default | | ------------- | ----------------------- | --------------------- | | baseUrl | User Facts API base URL | WRAL dev endpoint | | storageKey | localStorage key | wral_user_facts | | localTtlMs | Persistent cache TTL | 24 hours | | memoryTtlMs | In-memory cache TTL | 5 minutes | | storage | Persistence adapter | window.localStorage | | debug | Enable debug logging | false | | logger | Custom logger function | console.* |

API

getUserFacts(forceRefresh = false)

Fetch all user facts.

• Uses cache when available
• Set forceRefresh to bypass cache

const facts = await userFacts.getUserFacts(true);

getUserFact(factName)

Fetch a single fact by name.

const fact = await userFacts.getUserFact("favorite_team");

updateUserFact(factName, value, nonce?)

Create or update a fact.

• Uses optimistic updates
• Supports list-style and single-item facts

await userFacts.updateUserFact("favorite_team", "Hurricanes");

deleteUserFact(factName, nonce?)

Delete a fact (or a specific item when applicable).

await userFacts.deleteUserFact("favorite_team");

refreshUserFacts()

Force a refresh from the API, bypassing all caches.

await userFacts.refreshUserFacts();

isLoggedIn()

Check whether a valid ID token is available.

const loggedIn = await userFacts.isLoggedIn();

SSR Safety

• No access to window or localStorage at import time
• Persistence is lazily enabled only when available
• Safe to import in Node / SSR environments

Development

Lint

npm run lint

Test

npm test