@phygitallabs/tapquest-core 2.7.0 → 2.9.0

package/src/modules/generate-certificate/helpers/index.ts

@@ -0,0 +1,3 @@
+import { wrapTextWithFont } from "@phygitallabs/generate-certificate";
+
+export { wrapTextWithFont };

package/src/modules/generate-certificate/hooks/index.ts

@@ -1,8 +1,17 @@
-import { 
-    useGenerateThaocamvienCertificate,
-    useGenerateTemplateCertificate,
-    useGenerateFansipanCertificate
+import {
+  useGenerateThaocamvienCertificate,
+  useGenerateTemplateCertificate,
+  useGenerateFansipanCertificate,
+  useCreateCertificate,
+  useCreateCertificateAnonymous,
+  useCreateCertificateWithMask,
 } from "@phygitallabs/generate-certificate";
 
-
-export { useGenerateThaocamvienCertificate, useGenerateTemplateCertificate, useGenerateFansipanCertificate };
+export {
+  useGenerateThaocamvienCertificate,
+  useGenerateTemplateCertificate,
+  useGenerateFansipanCertificate,
+  useCreateCertificate,
+  useCreateCertificateAnonymous,
+  useCreateCertificateWithMask,
+};

package/src/modules/generate-certificate/index.ts

@@ -1,3 +1,5 @@
 export * from "./types";
 
-export * from "./hooks";
+export * from "./hooks";
+
+export * from "./helpers";

package/src/modules/notification/providers/index.tsx

@@ -16,7 +16,7 @@ interface NotificationCallbacks {
 interface NotificationProviderProps extends NotificationCallbacks {
   children: React.ReactNode;
   autoConnect?: boolean;
-  user: { id: string; accessToken: string | null };
+  user: { id?: string ; accessToken?: string };
   environment?: EnvironmentType;
 }
 
@@ -34,8 +34,8 @@ export const NotificationProvider: React.FC<NotificationProviderProps> = ({
 
   return (
       <NotificationProviderApi
-        userUid={user.id}
-        accessToken={user.accessToken}
+        userUid={user?.id}
+        accessToken={user?.accessToken ?? null}
         webSocketUrl={webSocketUrl}
         autoConnect={autoConnect}
         onWebSocketOpen={onWebSocketOpen}

package/src/modules/reward/hooks/useRewardService.ts

@@ -3,12 +3,12 @@ export {
   useManyUserRewards,
   useGetUserRewards,
   useClaimUserReward,
-  useApiListRewardModels as useListRewardModels,
-  useApiGetRewardModel as useGetRewardModel,
-  useApiCreateRewardModel as useCreateRewardModel,
-  useApiUpdateRewardModel as useUpdateRewardModel,
-  useApiDeleteRewardModel as useDeleteRewardModel,
+  useListRewardModels,
+  useGetRewardModel,
+  useCreateRewardModel,
+  useUpdateRewardModel,
+  useDeleteRewardModel,
   useCreateModelGroupReward,
   useClearUserRewardCache,
   useV1ListRewards
-} from "@phygitallabs/reward/src/hooks";
+} from "@phygitallabs/reward";

package/src/modules/session-replay/README.md

@@ -0,0 +1,334 @@
+# OpenReplay Session Replay Integration
+
+This module provides a React context-based integration for OpenReplay session replay tracking, following the official Next.js tracker context pattern.
+
+## Features
+
+- ✅ React Context API with reducer pattern
+- ✅ Dynamic user ID management with `setUserId` action
+- ✅ SSR-safe with dynamic imports
+- ✅ TypeScript support
+- ✅ Automatic or custom user ID generation
+- ✅ Flexible configuration options
+
+## Installation
+
+The module is already part of `@tapquest/core`. Make sure you have the required dependencies:
+
+```bash
+pnpm add @openreplay/tracker uuid
+pnpm add -D @types/uuid
+```
+
+## Basic Usage
+
+### 1. Wrap Your App with SessionReplayProvider
+
+In your `_app.tsx` or root layout file:
+
+```tsx
+import { SessionReplayProvider } from '@tapquest/core';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <SessionReplayProvider
+      config={{
+        projectKey: process.env.NEXT_PUBLIC_OPENREPLAY_PROJECT_KEY,
+        userIdEnabled: false, // Set to true to enable automatic UUID generation
+        debug: process.env.NODE_ENV === 'development',
+      }}
+    >
+      <Component {...pageProps} />
+    </SessionReplayProvider>
+  );
+}
+
+export default MyApp;
+```
+
+### 2. Initialize Tracker in a Component
+
+#### Option A: Using the `useSessionReplay` hook (Recommended)
+
+```tsx
+import { useEffect } from 'react';
+import { useSessionReplay } from '@tapquest/core';
+
+function MyComponent() {
+  const { initTracker, startTracking } = useSessionReplay();
+
+  useEffect(() => {
+    initTracker();
+    startTracking();
+  }, [initTracker, startTracking]);
+
+  return <div>Your content</div>;
+}
+```
+
+#### Option B: Using `TrackerContext` directly
+
+```tsx
+import { useContext, useEffect } from 'react';
+import { TrackerContext } from '@tapquest/core';
+
+function MyComponent() {
+  const tracker = useContext(TrackerContext);
+
+  useEffect(() => {
+    if (tracker) {
+      tracker.initTracker();
+      tracker.startTracking();
+    }
+  }, [tracker]);
+
+  return <div>Your content</div>;
+}
+```
+
+## Advanced Usage
+
+### Custom User ID Function
+
+Provide a custom function to generate user IDs based on your authentication system:
+
+```tsx
+import { SessionReplayProvider } from '@tapquest/core';
+import { useAuthStore } from './stores/authStore';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <SessionReplayProvider
+      config={{
+        projectKey: process.env.NEXT_PUBLIC_OPENREPLAY_PROJECT_KEY,
+        userIdEnabled: true,
+        getUserId: () => {
+          // Return the current user's ID from your auth system
+          const user = useAuthStore.getState().user;
+          return user?.id || user?.email || 'anonymous';
+        },
+        debug: process.env.NODE_ENV === 'development',
+      }}
+    >
+      <Component {...pageProps} />
+    </SessionReplayProvider>
+  );
+}
+```
+
+### Updating User ID After Login
+
+Use the `setUserId` action to update the user ID when a user logs in:
+
+```tsx
+import { useSessionReplay } from '@tapquest/core';
+
+function LoginComponent() {
+  const { setUserId } = useSessionReplay();
+
+  const handleLogin = async (credentials) => {
+    const user = await loginUser(credentials);
+
+    // Update the tracker with the authenticated user's ID
+    setUserId(user.id);
+  };
+
+  return <LoginForm onSubmit={handleLogin} />;
+}
+```
+
+### Self-Hosted OpenReplay
+
+For self-hosted OpenReplay instances, specify the ingest point:
+
+```tsx
+<SessionReplayProvider
+  config={{
+    projectKey: 'your-project-key',
+    ingestPoint: 'https://openreplay.yourdomain.com/ingest',
+    userIdEnabled: true,
+  }}
+>
+  {children}
+</SessionReplayProvider>
+```
+
+### Full Configuration Example
+
+```tsx
+import { SessionReplayProvider } from '@tapquest/core';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <SessionReplayProvider
+      config={{
+        // Required
+        projectKey: process.env.NEXT_PUBLIC_OPENREPLAY_PROJECT_KEY,
+
+        // User identification
+        userIdEnabled: true,
+        getUserId: () => getCurrentUser()?.id || 'anonymous',
+
+        // Custom ingest point (for self-hosted)
+        ingestPoint: 'https://openreplay.yourdomain.com/ingest',
+
+        // Capture options
+        captureExceptions: true,
+        capturePerformance: true,
+
+        // Network tracking
+        network: {
+          capturePayload: true,
+          sanitizer: (data) => {
+            // Redact sensitive information
+            if (data.request?.headers?.Authorization) {
+              data.request.headers.Authorization = '[REDACTED]';
+            }
+            return data;
+          },
+        },
+
+        // Console tracking
+        console: {
+          levels: ['error', 'warn', 'log'],
+        },
+
+        // Privacy settings
+        obscureTextEmails: true,
+        obscureTextNumbers: false,
+        obscureInputEmails: true,
+
+        // Development mode
+        debug: process.env.NODE_ENV === 'development',
+        __DISABLE_SECURE_MODE: process.env.NODE_ENV === 'development',
+      }}
+    >
+      <Component {...pageProps} />
+    </SessionReplayProvider>
+  );
+}
+```
+
+## API Reference
+
+### SessionReplayProvider Props
+
+```typescript
+interface SessionReplayProviderProps {
+  children: React.ReactNode;
+  config?: OpenReplayConfig;
+}
+```
+
+### OpenReplayConfig
+
+```typescript
+interface OpenReplayConfig {
+  projectKey?: string;
+  ingestPoint?: string;
+  userIdEnabled?: boolean;
+  getUserId?: () => string;
+  debug?: boolean;
+  captureExceptions?: boolean;
+  capturePerformance?: boolean;
+  network?: {
+    capturePayload?: boolean;
+    sanitizer?: (data: any) => any;
+  };
+  console?: {
+    levels?: Array<"error" | "warn" | "log" | "info" | "debug">;
+  };
+  obscureTextEmails?: boolean;
+  obscureTextNumbers?: boolean;
+  obscureInputEmails?: boolean;
+  __DISABLE_SECURE_MODE?: boolean;
+}
+```
+
+### TrackerContextValue
+
+```typescript
+interface TrackerContextValue {
+  initTracker: () => void;
+  startTracking: () => void;
+  setUserId: (userId: string) => void;
+}
+```
+
+## Environment Variables
+
+Store your OpenReplay project key in an environment variable:
+
+```bash
+# .env.local
+NEXT_PUBLIC_OPENREPLAY_PROJECT_KEY=your_project_key_here
+```
+
+**Note:** Use the `NEXT_PUBLIC_` prefix to make the variable accessible in the browser.
+
+## Best Practices
+
+1. **Initialize Once**: Call `initTracker()` and `startTracking()` once when your app loads, typically in a root-level component or effect.
+
+2. **Update User ID After Auth**: Use `setUserId()` after successful login to associate sessions with authenticated users.
+
+3. **Sanitize Sensitive Data**: Use the `network.sanitizer` function to redact sensitive information like API keys, passwords, and PII.
+
+4. **Use Environment Variables**: Never hardcode your project key. Use environment variables with the `NEXT_PUBLIC_` prefix.
+
+5. **Enable Debug Mode in Development**: Set `debug: true` in development to see tracker logs in the console.
+
+## Migration from Previous Implementation
+
+If you're migrating from the old `useEffect`-based implementation:
+
+**Before:**
+```tsx
+// Provider auto-initialized and started tracking
+<SessionReplayProvider config={{ projectKey, userId: user.id }}>
+  {children}
+</SessionReplayProvider>
+```
+
+**After:**
+```tsx
+// Provider requires explicit initialization
+<SessionReplayProvider config={{ projectKey, userIdEnabled: true }}>
+  {children}
+</SessionReplayProvider>
+
+// In a component:
+const tracker = useContext(TrackerContext);
+useEffect(() => {
+  tracker?.initTracker();
+  tracker?.startTracking();
+}, []);
+
+// Update user ID dynamically:
+tracker?.setUserId(user.id);
+```
+
+## Troubleshooting
+
+### Tracker not initializing
+
+- Ensure you're calling `initTracker()` before `startTracking()`
+- Check that your project key is set correctly
+- Verify you're in a browser environment (not SSR)
+
+### User ID not updating
+
+- Make sure `userIdEnabled` is set to `true`
+- Call `setUserId()` after the tracker is initialized
+- Check debug logs to verify the user ID was set
+
+### TypeScript errors
+
+- Ensure you're importing types from `@tapquest/core`
+- Verify that `TrackerContext` returns a non-null value before using it
+
+## Links
+
+- [OpenReplay Documentation](https://docs.openreplay.com/)
+- [OpenReplay Next.js Integration](https://docs.openreplay.com/en/using-or/next/)
+- [OpenReplay Tracker API](https://docs.openreplay.com/en/using-or/tracker-api/)

package/src/modules/session-replay/hooks/useSessionReplay.ts

@@ -0,0 +1,16 @@
+import { useContext } from "react";
+import { TrackerContext } from "../providers/SessionReplayProvider";
+import { TrackerContextValue } from "../types";
+
+export function useSessionReplay(): TrackerContextValue {
+    const context = useContext(TrackerContext);
+
+    if (!context) {
+        throw new Error(
+            "useSessionReplay must be used within a SessionReplayProvider. " +
+            "Make sure your component is wrapped with <SessionReplayProvider>."
+        );
+    }
+
+    return context;
+}

package/src/modules/session-replay/index.ts

@@ -0,0 +1,10 @@
+export { SessionReplayProvider, TrackerContext } from "./providers/SessionReplayProvider";
+export { useSessionReplay } from "./hooks/useSessionReplay";
+export type {
+    OpenReplayConfig,
+    SessionReplayProviderProps,
+    TrackerContextValue,
+    TrackerState,
+    TrackerAction,
+} from "./types";
+export * from "./utils";

package/src/modules/session-replay/providers/SessionReplayProvider.tsx

@@ -0,0 +1,189 @@
+import React, { createContext, useEffect, useReducer } from "react";
+import { v4 as uuidV4 } from "uuid";
+
+import {
+    SessionReplayProviderProps,
+    TrackerState,
+    TrackerAction,
+    TrackerContextValue,
+    OpenReplayConfig,
+} from "../types";
+
+import {
+    isBrowser
+} from "../utils";
+
+export const TrackerContext = createContext<TrackerContextValue | null>(null);
+
+function defaultGetUserId(): string {
+    return uuidV4();
+}
+
+async function newTracker(config: OpenReplayConfig) {
+    try {
+        // Dynamic import for SSR compatibility
+        const OpenReplay = (await import("@openreplay/tracker")).default;
+
+        // Get user ID function (custom or default UUID generator)
+        const getUserId =
+            config?.userIdEnabled && config?.getUserId
+                ? config.getUserId
+                : defaultGetUserId;
+
+        // Build tracker configuration
+        const trackerConfig: any = {
+            projectKey:
+                config?.projectKey || process.env.NEXT_PUBLIC_OPENREPLAY_PROJECT_KEY,
+            ingestPoint: config?.ingestPoint,
+            // Capture options
+            captureExceptions: config.captureExceptions ?? true,
+            capturePerformance: config.capturePerformance ?? true,
+            // Network tracking
+            network: config.network || {
+                capturePayload: true,
+                sanitizer: (data: any) => data,
+            },
+            // Console tracking
+            console: config.console || {
+                levels: ["error", "warn", "log"],
+            },
+            // Privacy settings
+            obscureTextEmails: config.obscureTextEmails ?? true,
+            obscureTextNumbers: config.obscureTextNumbers ?? false,
+            obscureInputEmails: config.obscureInputEmails ?? true,
+            // Development mode
+            __DISABLE_SECURE_MODE:
+                config.__DISABLE_SECURE_MODE ??
+                (typeof process !== "undefined" && process.env?.NODE_ENV === "development"),
+        };
+
+        // Initialize tracker
+        const tracker = new OpenReplay(trackerConfig);
+
+        // Set user ID if enabled
+        if (config?.userIdEnabled) {
+            const userId = getUserId();
+            tracker.setUserID(userId);
+            console.log("User ID set:", userId);
+        }
+
+        console.log("OpenReplay tracker initialized");
+        console.log("Project Key:", trackerConfig.projectKey);
+        console.log("Ingest Point:", trackerConfig.ingestPoint);
+
+        return tracker;
+    } catch (error: any) {
+        console.error("Failed to create tracker:", error);
+        throw error;
+    }
+}
+
+function reducer(state: TrackerState, action: TrackerAction): TrackerState {
+    const { debug = false } = state.config;
+
+    switch (action.type) {
+        case "init":
+            // Only initialize if tracker doesn't exist and we're in browser
+            if (!state.tracker && isBrowser()) {
+                if (!state.config.projectKey && !process.env.NEXT_PUBLIC_OPENREPLAY_PROJECT_KEY) {
+                    console.warn(
+                        debug,
+                        "Project key not found. Skipping session replay initialization."
+                    );
+                    return state;
+                }
+
+                // Return state with tracker promise
+                // The tracker will be created asynchronously
+                return {
+                    ...state,
+                    tracker: newTracker(state.config),
+                };
+            }
+            return state;
+
+        case "start":
+            // Start tracking if tracker exists
+            if (state.tracker) {
+                Promise.resolve(state.tracker)
+                    .then((tracker) => {
+                        tracker.start();
+                        console.log(debug, "Session replay tracker started");
+                    })
+                    .catch((error) => {
+                        console.error("Failed to start tracker:", error);
+                    });
+            } else {
+                console.warn(debug, "Tracker not initialized. Call initTracker() first.");
+            }
+            return state;
+
+        case "setUserId":
+            // Set or update user ID
+            if (state.tracker) {
+                Promise.resolve(state.tracker)
+                    .then((tracker) => {
+                        tracker.setUserID(action.payload);
+                        console.log(debug, "User ID updated:", action.payload);
+                    })
+                    .catch((error) => {
+                        console.error("Failed to set user ID:", error);
+                    });
+            } else {
+                console.warn(debug, "Tracker not initialized. Call initTracker() first.");
+            }
+            return state;
+
+        // Set metadata
+        case "setMetadata":
+            if (state.tracker) {
+                Promise.resolve(state.tracker)
+                    .then((tracker) => {
+                        Object.entries(action.payload || {})?.forEach(([key, value]) => {
+                            tracker.setMetadata(key, value);
+                        });
+
+                        console.log(debug, "Metadata updated:", action.payload.metadata);
+                    })
+                    .catch((error) => {
+                        console.error("Failed to set metadata:", error);
+                    });
+            } else {
+                console.warn(debug, "Tracker not initialized. Call initTracker() first.");
+            }
+            return state;
+
+        default:
+            return state;
+    }
+}
+
+export const SessionReplayProvider: React.FC<SessionReplayProviderProps> = ({
+    children,
+    config = {},
+}) => {
+    const [, dispatch] = useReducer(reducer, {
+        tracker: null,
+        config,
+    });
+
+    const initTracker = () => dispatch({ type: "init" })
+    const startTracking = () => dispatch({ type: "start" })
+    const setUserId = (userId: string) => dispatch({ type: "setUserId", payload: userId })
+    const setMetadata = (metadata: Record<string, any>) => dispatch({ type: "setMetadata", payload: metadata })
+
+    // init and start tracker
+    useEffect(() => {
+        initTracker();
+        startTracking();
+    }, []);
+
+    return <TrackerContext.Provider value={{
+        initTracker,
+        startTracking,
+        setUserId,
+        setMetadata
+    }}>{children}</TrackerContext.Provider>;
+};
+
+export default SessionReplayProvider;