@payez/next-mvp 4.1.11 → 4.1.20

package/src/hooks/useProfile.ts

@@ -1,75 +1,75 @@
-'use client';
-
-/**
- * ⚠️ WARNING: This hook cannot be used directly from the @payez/next-mvp package!
- *
- * @deprecated Import this hook from your local app instead
- *
- * **Why?** This hook depends on useAuth, which requires SessionProvider context that cannot cross package boundaries.
- *
- * **Solution:** Create a local version in your app (e.g., src/hooks/useProfile.ts):
- *
- * @example
- * ```typescript
- * // src/hooks/useProfile.ts (YOUR APP)
- * 'use client';
- * import { useQuery } from '@tanstack/react-query';
- * import { useAuth } from './useAuth'; // Your local useAuth
- * import { isApiSuccess } from '@payez/next-mvp/lib/standardized-client-api';
- *
- * export function useProfile() {
- *   const { isAuthenticated, apiCall } = useAuth();
- *   return useQuery({
- *     queryKey: ['account', 'profile'],
- *     enabled: isAuthenticated,
- *     queryFn: async () => {
- *       const result = await apiCall('/api/account/profile', 'GET');
- *       if (isApiSuccess(result)) return result.data;
- *       throw new Error(result.message);
- *     }
- *   });
- * }
- * ```
- *
- * @see {@link https://github.com/payez/next-mvp/blob/main/docs/centralized-auth-api-pattern.md#usage-patterns Complete documentation}
- */
-
-import { useQuery } from '@tanstack/react-query';
-import { useAuth } from './useAuth';
-import { isApiSuccess, isApiError } from '../lib/standardized-client-api';
-
-export type ProfileResponse = {
-  email: string;
-  user_id?: string;
-  first_name?: string;
-  last_name?: string;
-  full_name?: string;
-  phone_number?: string;
-  email_confirmed?: boolean;
-  phone_confirmed?: boolean;
-  two_factor_enabled?: boolean;
-  roles?: string[];
-  contact_information?: Record<string, any>;
-  [key: string]: any;
-};
-
-export function useProfile() {
-  const { isAuthenticated, apiCall } = useAuth();
-
-  return useQuery<ProfileResponse, Error>({
-    queryKey: ['account', 'profile'],
-    enabled: isAuthenticated,
-    queryFn: async () => {
-      const result = await apiCall<ProfileResponse>('/api/account/profile', 'GET');
-      if (isApiSuccess(result)) {
-        return result.data;
-      }
-      // If API returned standardized error
-      if (isApiError(result)) {
-        throw new Error(result.message || 'Failed to load profile');
-      }
-      throw new Error('Failed to load profile');
-    },
-    staleTime: 5 * 60 * 1000,
-  });
-}
+'use client';
+
+/**
+ * ⚠️ WARNING: This hook cannot be used directly from the @payez/next-mvp package!
+ *
+ * @deprecated Import this hook from your local app instead
+ *
+ * **Why?** This hook depends on useAuth, which requires SessionProvider context that cannot cross package boundaries.
+ *
+ * **Solution:** Create a local version in your app (e.g., src/hooks/useProfile.ts):
+ *
+ * @example
+ * ```typescript
+ * // src/hooks/useProfile.ts (YOUR APP)
+ * 'use client';
+ * import { useQuery } from '@tanstack/react-query';
+ * import { useAuth } from './useAuth'; // Your local useAuth
+ * import { isApiSuccess } from '@payez/next-mvp/lib/standardized-client-api';
+ *
+ * export function useProfile() {
+ *   const { isAuthenticated, apiCall } = useAuth();
+ *   return useQuery({
+ *     queryKey: ['account', 'profile'],
+ *     enabled: isAuthenticated,
+ *     queryFn: async () => {
+ *       const result = await apiCall('/api/account/profile', 'GET');
+ *       if (isApiSuccess(result)) return result.data;
+ *       throw new Error(result.message);
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/payez/next-mvp/blob/main/docs/centralized-auth-api-pattern.md#usage-patterns Complete documentation}
+ */
+
+import { useQuery } from '@tanstack/react-query';
+import { useAuth } from './useAuth';
+import { isApiSuccess, isApiError } from '../lib/standardized-client-api';
+
+export type ProfileResponse = {
+  email: string;
+  user_id?: string;
+  first_name?: string;
+  last_name?: string;
+  full_name?: string;
+  phone_number?: string;
+  email_confirmed?: boolean;
+  phone_confirmed?: boolean;
+  two_factor_enabled?: boolean;
+  roles?: string[];
+  contact_information?: Record<string, any>;
+  [key: string]: any;
+};
+
+export function useProfile() {
+  const { isAuthenticated, apiCall } = useAuth();
+
+  return useQuery<ProfileResponse, Error>({
+    queryKey: ['account', 'profile'],
+    enabled: isAuthenticated,
+    queryFn: async () => {
+      const result = await apiCall<ProfileResponse>('/api/account/profile', 'GET');
+      if (isApiSuccess(result)) {
+        return result.data;
+      }
+      // If API returned standardized error
+      if (isApiError(result)) {
+        throw new Error(result.message || 'Failed to load profile');
+      }
+      throw new Error('Failed to load profile');
+    },
+    staleTime: 5 * 60 * 1000,
+  });
+}

package/src/lib/anon-session.ts

@@ -1,213 +1,213 @@
-/**
- * Anonymous Session Store for `@payez/next-mvp`
- *
- * Provides Redis-backed anonymous sessions for tracking user preferences
- * before they log in. When a user logs in, their anonymous session can be
- * merged into their authenticated session.
- *
- * Key features:
- * - Generates a unique visitor ID on first visit
- * - Stores preferences (theme, locale, etc.) in Redis
- * - Tracks usage metrics (resume count for free tier, etc.)
- * - Provides merge functionality when user authenticates
- */
-
-import redis from './redis';
-import { randomBytes } from 'crypto';
-import { getAnonPrefix, getAnonCookieName } from './app-slug';
-
-// Use app-slug prefixes for multi-app isolation
-const getAnonKey = (id: string) => `${getAnonPrefix()}${id}`;
-
-const ANON_SESSION_TTL = 90 * 24 * 60 * 60; // 90 days in seconds
-
-// Export dynamic cookie name getter for external use
-export const ANON_COOKIE_NAME = getAnonCookieName();
-
-export interface AnonSessionPreferences {
-  theme?: string;
-  locale?: string;
-  [key: string]: any;
-}
-
-export interface AnonSessionMetrics {
-  resumeGenerationCount?: number;
-  firstVisit?: number;
-  lastVisit?: number;
-  visitCount?: number;
-  [key: string]: any;
-}
-
-export interface AnonSessionData {
-  id: string;
-  createdAt: number;
-  updatedAt: number;
-  preferences: AnonSessionPreferences;
-  metrics: AnonSessionMetrics;
-}
-
-/**
- * Generates a new anonymous session ID
- */
-export function generateAnonId(): string {
-  return randomBytes(16).toString('hex');
-}
-
-// getAnonKey is defined above using app-slug prefix
-
-/**
- * Creates a new anonymous session in Redis
- */
-export async function createAnonSession(anonId?: string): Promise<AnonSessionData> {
-  const id = anonId || generateAnonId();
-  const now = Date.now();
-
-  const session: AnonSessionData = {
-    id,
-    createdAt: now,
-    updatedAt: now,
-    preferences: {},
-    metrics: {
-      firstVisit: now,
-      lastVisit: now,
-      visitCount: 1,
-    },
-  };
-
-  const key = getAnonKey(id);
-  await redis.setex(key, ANON_SESSION_TTL, JSON.stringify(session));
-
-  return session;
-}
-
-/**
- * Retrieves an anonymous session from Redis
- */
-export async function getAnonSession(anonId: string): Promise<AnonSessionData | null> {
-  if (!anonId) return null;
-
-  const key = getAnonKey(anonId);
-  const json = await redis.get(key);
-
-  if (!json) return null;
-
-  try {
-    return JSON.parse(json) as AnonSessionData;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Gets or creates an anonymous session
- */
-export async function getOrCreateAnonSession(anonId?: string): Promise<AnonSessionData> {
-  if (anonId) {
-    const existing = await getAnonSession(anonId);
-    if (existing) {
-      // Update last visit
-      existing.updatedAt = Date.now();
-      existing.metrics.lastVisit = Date.now();
-      existing.metrics.visitCount = (existing.metrics.visitCount || 0) + 1;
-      await saveAnonSession(existing);
-      return existing;
-    }
-  }
-
-  // Create new session
-  return createAnonSession(anonId);
-}
-
-/**
- * Saves an anonymous session to Redis
- */
-export async function saveAnonSession(session: AnonSessionData): Promise<void> {
-  session.updatedAt = Date.now();
-  const key = getAnonKey(session.id);
-  await redis.setex(key, ANON_SESSION_TTL, JSON.stringify(session));
-}
-
-/**
- * Updates preferences in an anonymous session
- */
-export async function updateAnonPreferences(
-  anonId: string,
-  preferences: Partial<AnonSessionPreferences>
-): Promise<AnonSessionData | null> {
-  const session = await getAnonSession(anonId);
-  if (!session) return null;
-
-  session.preferences = { ...session.preferences, ...preferences };
-  await saveAnonSession(session);
-
-  return session;
-}
-
-/**
- * Updates metrics in an anonymous session
- */
-export async function updateAnonMetrics(
-  anonId: string,
-  metrics: Partial<AnonSessionMetrics>
-): Promise<AnonSessionData | null> {
-  const session = await getAnonSession(anonId);
-  if (!session) return null;
-
-  session.metrics = { ...session.metrics, ...metrics };
-  await saveAnonSession(session);
-
-  return session;
-}
-
-/**
- * Increments a numeric metric
- */
-export async function incrementAnonMetric(
-  anonId: string,
-  metricName: string,
-  amount: number = 1
-): Promise<number> {
-  const session = await getAnonSession(anonId);
-  if (!session) return 0;
-
-  const currentValue = (session.metrics[metricName] as number) || 0;
-  const newValue = currentValue + amount;
-  session.metrics[metricName] = newValue;
-  await saveAnonSession(session);
-
-  return newValue;
-}
-
-/**
- * Deletes an anonymous session
- */
-export async function deleteAnonSession(anonId: string): Promise<void> {
-  if (!anonId) return;
-  const key = getAnonKey(anonId);
-  await redis.del(key);
-}
-
-/**
- * Merges anonymous session data into user profile data
- * Call this when a user logs in to preserve their pre-login preferences
- */
-export async function mergeAnonSessionToUser(
-  anonId: string,
-  userId: string,
-  mergeCallback?: (anonData: AnonSessionData, userId: string) => Promise<void>
-): Promise<AnonSessionData | null> {
-  const anonSession = await getAnonSession(anonId);
-  if (!anonSession) return null;
-
-  // If a merge callback is provided, use it to persist data to user profile
-  if (mergeCallback) {
-    await mergeCallback(anonSession, userId);
-  }
-
-  // Optionally delete the anonymous session after merge
-  // await deleteAnonSession(anonId);
-
-  return anonSession;
-}
-
-// ANON_COOKIE_NAME is already exported at the top of the file
+/**
+ * Anonymous Session Store for `@payez/next-mvp`
+ *
+ * Provides Redis-backed anonymous sessions for tracking user preferences
+ * before they log in. When a user logs in, their anonymous session can be
+ * merged into their authenticated session.
+ *
+ * Key features:
+ * - Generates a unique visitor ID on first visit
+ * - Stores preferences (theme, locale, etc.) in Redis
+ * - Tracks usage metrics (resume count for free tier, etc.)
+ * - Provides merge functionality when user authenticates
+ */
+
+import redis from './redis';
+import { randomBytes } from 'crypto';
+import { getAnonPrefix, getAnonCookieName } from './app-slug';
+
+// Use app-slug prefixes for multi-app isolation
+const getAnonKey = (id: string) => `${getAnonPrefix()}${id}`;
+
+const ANON_SESSION_TTL = 90 * 24 * 60 * 60; // 90 days in seconds
+
+// Export dynamic cookie name getter for external use
+export const ANON_COOKIE_NAME = getAnonCookieName();
+
+export interface AnonSessionPreferences {
+  theme?: string;
+  locale?: string;
+  [key: string]: any;
+}
+
+export interface AnonSessionMetrics {
+  resumeGenerationCount?: number;
+  firstVisit?: number;
+  lastVisit?: number;
+  visitCount?: number;
+  [key: string]: any;
+}
+
+export interface AnonSessionData {
+  id: string;
+  createdAt: number;
+  updatedAt: number;
+  preferences: AnonSessionPreferences;
+  metrics: AnonSessionMetrics;
+}
+
+/**
+ * Generates a new anonymous session ID
+ */
+export function generateAnonId(): string {
+  return randomBytes(16).toString('hex');
+}
+
+// getAnonKey is defined above using app-slug prefix
+
+/**
+ * Creates a new anonymous session in Redis
+ */
+export async function createAnonSession(anonId?: string): Promise<AnonSessionData> {
+  const id = anonId || generateAnonId();
+  const now = Date.now();
+
+  const session: AnonSessionData = {
+    id,
+    createdAt: now,
+    updatedAt: now,
+    preferences: {},
+    metrics: {
+      firstVisit: now,
+      lastVisit: now,
+      visitCount: 1,
+    },
+  };
+
+  const key = getAnonKey(id);
+  await redis.setex(key, ANON_SESSION_TTL, JSON.stringify(session));
+
+  return session;
+}
+
+/**
+ * Retrieves an anonymous session from Redis
+ */
+export async function getAnonSession(anonId: string): Promise<AnonSessionData | null> {
+  if (!anonId) return null;
+
+  const key = getAnonKey(anonId);
+  const json = await redis.get(key);
+
+  if (!json) return null;
+
+  try {
+    return JSON.parse(json) as AnonSessionData;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gets or creates an anonymous session
+ */
+export async function getOrCreateAnonSession(anonId?: string): Promise<AnonSessionData> {
+  if (anonId) {
+    const existing = await getAnonSession(anonId);
+    if (existing) {
+      // Update last visit
+      existing.updatedAt = Date.now();
+      existing.metrics.lastVisit = Date.now();
+      existing.metrics.visitCount = (existing.metrics.visitCount || 0) + 1;
+      await saveAnonSession(existing);
+      return existing;
+    }
+  }
+
+  // Create new session
+  return createAnonSession(anonId);
+}
+
+/**
+ * Saves an anonymous session to Redis
+ */
+export async function saveAnonSession(session: AnonSessionData): Promise<void> {
+  session.updatedAt = Date.now();
+  const key = getAnonKey(session.id);
+  await redis.setex(key, ANON_SESSION_TTL, JSON.stringify(session));
+}
+
+/**
+ * Updates preferences in an anonymous session
+ */
+export async function updateAnonPreferences(
+  anonId: string,
+  preferences: Partial<AnonSessionPreferences>
+): Promise<AnonSessionData | null> {
+  const session = await getAnonSession(anonId);
+  if (!session) return null;
+
+  session.preferences = { ...session.preferences, ...preferences };
+  await saveAnonSession(session);
+
+  return session;
+}
+
+/**
+ * Updates metrics in an anonymous session
+ */
+export async function updateAnonMetrics(
+  anonId: string,
+  metrics: Partial<AnonSessionMetrics>
+): Promise<AnonSessionData | null> {
+  const session = await getAnonSession(anonId);
+  if (!session) return null;
+
+  session.metrics = { ...session.metrics, ...metrics };
+  await saveAnonSession(session);
+
+  return session;
+}
+
+/**
+ * Increments a numeric metric
+ */
+export async function incrementAnonMetric(
+  anonId: string,
+  metricName: string,
+  amount: number = 1
+): Promise<number> {
+  const session = await getAnonSession(anonId);
+  if (!session) return 0;
+
+  const currentValue = (session.metrics[metricName] as number) || 0;
+  const newValue = currentValue + amount;
+  session.metrics[metricName] = newValue;
+  await saveAnonSession(session);
+
+  return newValue;
+}
+
+/**
+ * Deletes an anonymous session
+ */
+export async function deleteAnonSession(anonId: string): Promise<void> {
+  if (!anonId) return;
+  const key = getAnonKey(anonId);
+  await redis.del(key);
+}
+
+/**
+ * Merges anonymous session data into user profile data
+ * Call this when a user logs in to preserve their pre-login preferences
+ */
+export async function mergeAnonSessionToUser(
+  anonId: string,
+  userId: string,
+  mergeCallback?: (anonData: AnonSessionData, userId: string) => Promise<void>
+): Promise<AnonSessionData | null> {
+  const anonSession = await getAnonSession(anonId);
+  if (!anonSession) return null;
+
+  // If a merge callback is provided, use it to persist data to user profile
+  if (mergeCallback) {
+    await mergeCallback(anonSession, userId);
+  }
+
+  // Optionally delete the anonymous session after merge
+  // await deleteAnonSession(anonId);
+
+  return anonSession;
+}
+
+// ANON_COOKIE_NAME is already exported at the top of the file