feat: add supabase publishable events (#115)

* feat: add supabase pblishable events

* fix: remove undeclared package from lock

* refactor: make attempt_id indexable

Author: ShaunSHamilton

.github/workflows/publish.yml

@@ -323,6 +323,8 @@ jobs:
           SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
           FREECODECAMP_API: ${{ env.FREECODECAMP_API }}
           ENVIRONMENT: ${{inputs.environment}}
+          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+          SUPABASE_PUBLISHABLE: ${{ secrets.SUPABASE_PUBLISHABLE }}
         with:
           releaseId: ${{ needs.create-release.outputs.release_id }}
           args: ${{ steps.build-args.outputs.args }} ${{ env.TAURI_VERBOSE_FLAG }}

bun.lock

@@ -19,6 +19,7 @@
     "@freecodecamp/ui": "4.3.0",
     "@sentry/react": "10.27.0",
     "@sentry/vite-plugin": "4.6.1",
+    "@supabase/supabase-js": "2.90.0",
     "@tanstack/react-query": "5.90.11",
     "@tanstack/react-router": "1.139.12",
     "@tauri-apps/api": "2.9.1",

package.json

@@ -9,3 +9,6 @@ AZURE_TENANT_ID=azure-tenant-id
 AZURE_CERTIFICATE_URI=https://prd-exam-environment.vault.azure.net/certificates/prd-exam-environment
 AZURE_CLIENT_SECRET=azure-client-secret
 AZURE_CLIENT_ID=azure-client-id
+
+SUPABASE_URL=""
+SUPABASE_PUBLISHABLE=""

sample.env

@@ -33,6 +33,9 @@
         },
         {
           "url": "https://api.github.com"
+        },
+        {
+          "url": "https://*.supabase.co"
         }
       ]
     },

src-tauri/capabilities/default.json

@@ -1,12 +1,12 @@
 import { Box, Divider, Text } from "@chakra-ui/react";
 import { QuizQuestion } from "@freecodecamp/ui";
-import { useEffect, useRef } from "react";
+import { SyntheticEvent, useEffect, useRef } from "react";
 
 import { Answers, FullQuestion, UserExamAttempt } from "../utils/types";
 import { AudioPlayer } from "./audio-player";
 import { parseMarkdown } from "../utils/markdown";
 import { PrismFormatted } from "./prism-formatted";
-import { logger } from "@sentry/react";
+import { captureEvent, createEvent, EventKind } from "../utils/superbase";
 
 type QuestionTypeFormProps = {
   fullQuestion: FullQuestion;
@@ -21,16 +21,17 @@ export function QuestionSetForm({
   setNewSelectedAnswers,
   examAttempt,
 }: QuestionTypeFormProps) {
-  const captionsRef = useRef<HTMLDetailsElement>(null);
+  const lastTrackedId = useRef<string | null>(null);
 
-  useEffect(() => {
-    if (captionsRef.current?.open) {
-      logger.info("captions opened", {
-        exam: examAttempt.examId,
-        question: fullQuestion.id,
-      });
+  function captionsToggled(e: SyntheticEvent<HTMLDetailsElement, Event>) {
+    if (e.currentTarget.open) {
+      captureEvent(
+        createEvent(EventKind.CAPTIONS_OPENED, examAttempt.id, {
+          question: fullQuestion.id,
+        })
+      );
     }
-  }, [captionsRef.current?.open]);
+  }
 
   useEffect(() => {
     setNewSelectedAnswers(
@@ -42,6 +43,15 @@ export function QuestionSetForm({
         )
         .map((a) => a.id)
     );
+
+    if (lastTrackedId.current !== fullQuestion.id) {
+      captureEvent(
+        createEvent(EventKind.QUESTION_VISIT, examAttempt.id, {
+          question: fullQuestion.id,
+        })
+      );
+      lastTrackedId.current = fullQuestion.id;
+    }
   }, [fullQuestion]);
 
   return (
@@ -56,13 +66,13 @@ export function QuestionSetForm({
           <Divider />
         </>
       )}
-      {fullQuestion.audio && (
+      {!!fullQuestion.audio?.url && (
         <Box mb={"2em"} mt={"2em"}>
           <Text>Please listen to the following audio fragment:</Text>
           {/* NOTE: `fullQuestion` is passed to cause the whole component to rerender - correctly resetting the audio */}
           <AudioPlayer fullQuestion={fullQuestion} />
           {fullQuestion.audio.captions && (
-            <details style={{ cursor: "pointer" }} ref={captionsRef}>
+            <details style={{ cursor: "pointer" }} onToggle={captionsToggled}>
               <summary>Show captions</summary>
               <Box marginTop="1em">
                 <PrismFormatted

src/components/question-set-form.tsx

@@ -0,0 +1,64 @@
+import { getCurrentWindow } from "@tauri-apps/api/window";
+import { useEffect } from "react";
+
+export type AppFocusProps = {
+  onFocusChanged: (focused: boolean) => void;
+};
+
+/**
+ * A hook to attach a callback for whenever the app window's focus changes.
+ *
+ * As the focus event handler is immediately attached, a ref can be used to prevent always running on focus changes and prevent unnecessary rerenders.
+ *
+ * **Usage**
+ *
+ * ```tsx
+ * function myComponent() {
+ *   const runFocusRef = useRef(false);
+ *
+ *   function onFocusChanged(focused: boolean) {
+ *     if (runFocusRef.current) {
+ *       console.log(focused);
+ *     }
+ *   }
+ *   useAppFocus({onFocusChanged});
+ *
+ *   return (
+ *     <button
+ *       onClick={() => {
+ *         runFocusRef.current = !runFocusRef.current;
+ *       }}
+ *     >
+ *       Toogle focus runner
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * TODO: Consider returning `listen` and `unlisten` functions
+ *
+ */
+export function useAppFocus({ onFocusChanged }: AppFocusProps) {
+  // TODO: Once useEffectiveEvent is stabalised
+  // const onChange = useEffectiveEvent(onFocusChanged);
+
+  async function listen() {
+    const unlisten = await getCurrentWindow().onFocusChanged(
+      ({ payload: focused }) => {
+        onFocusChanged(focused);
+      }
+    );
+
+    return unlisten;
+  }
+
+  useEffect(() => {
+    // TODO: What to do if unlisten function is not yet attached to ref?
+    const unlisten = listen();
+
+    return () => {
+      // If component is unmounted, listener MUST be unlistened
+      unlisten?.then((u) => u());
+    };
+  }, [onFocusChanged]);
+}

src/components/use-app-focus.tsx

@@ -32,6 +32,8 @@ import { getErrorMessage } from "../utils/errors";
 import { ExamSubmissionModal } from "../components/exam-submission-modal";
 import { QuestionSubmissionErrorModal } from "../components/question-submission-error-modal";
 import { produce } from "immer";
+import { useAppFocus } from "../components/use-app-focus";
+import { captureEvent, createEvent, EventKind } from "../utils/superbase";
 
 export function Exam() {
   const { examId } = ExamRoute.useParams();
@@ -268,6 +270,23 @@ export function Exam() {
     [questions, activeQuestionId]
   );
 
+  const onFocusChanged = useCallback(
+    (focused: boolean) => {
+      if (!examAttempt || !fullQuestion) return;
+
+      const eventKind = focused ? EventKind.FOCUS : EventKind.BLUR;
+
+      captureEvent(
+        createEvent(eventKind, examAttempt.id, {
+          question: fullQuestion.id,
+        })
+      );
+    },
+    [examAttempt, fullQuestion]
+  );
+
+  useAppFocus({ onFocusChanged });
+
   if (examQuery.isPending) {
     return (
       <Box overflowY="hidden">

src/pages/exam.tsx

@@ -0,0 +1,55 @@
+import { createClient } from "@supabase/supabase-js";
+import { fetch } from "@tauri-apps/plugin-http";
+
+export const supabase = createClient(
+  __SUPABASE_URL__,
+  __SUPABASE_PUBLISHABLE__,
+  {
+    global: {
+      // @ts-expect-error Unknown error
+      fetch: fetch.bind(globalThis),
+    },
+  },
+);
+
+export const EventKind = {
+  CAPTIONS_OPENED: "CAPTIONS_OPENED",
+  QUESTION_VISIT: "QUESTION_VISIT",
+  FOCUS: "FOCUS",
+  BLUR: "BLUR",
+  EXAM_EXIT: "EXAM_EXIT",
+} as const;
+
+type Meta = Record<string, unknown>;
+
+interface Event {
+  kind: keyof typeof EventKind;
+  // timestamp: Date;
+  meta: Meta | null;
+  // ObjectId
+  attempt_id: string;
+}
+
+export async function captureEvent(event: Event) {
+  try {
+    const res = await supabase.from("events").insert(event);
+    console.debug(
+      event,
+      res.count,
+      res.data,
+      res.error,
+      res.status,
+      res.statusText,
+    );
+  } catch (e) {
+    console.log(e);
+  }
+}
+
+export function createEvent(
+  kind: Event["kind"],
+  attempt_id: Event["attempt_id"],
+  meta: Event["meta"] = null,
+): Event {
+  return { kind, meta, attempt_id };
+}

src/utils/superbase.ts

@@ -3,3 +3,5 @@ declare const __APP_VERSION__: string;
 declare const __SENTRY_DSN__: string;
 declare const __FREECODECAMP_API__: string;
 declare const __ENVIRONMENT__: string;
+declare const __SUPABASE_URL__: string;
+declare const __SUPABASE_PUBLISHABLE__: string;