Expanding widget convex wrapper hooks

apps/widget/src/AuthoringOverlay.tsx

@@ -1,10 +1,14 @@
 import { useState, useEffect, useCallback, useRef, useMemo } from "react";
-import { useQuery, useMutation } from "convex/react";
-import { makeFunctionReference } from "convex/server";
 import type { Id } from "@opencom/convex/dataModel";
 import { normalizeUnknownError, type ErrorFeedbackMessage } from "@opencom/web-shared";
 import { scoreSelectorQuality } from "@opencom/sdk-core";
 import { ErrorFeedbackBanner } from "./components/ErrorFeedbackBanner";
+import {
+  useWidgetMutation,
+  useWidgetQuery,
+  widgetMutationRef,
+  widgetQueryRef,
+} from "./lib/convex/hooks";
 
 interface TourStep {
   _id: Id<"tourSteps">;
@@ -46,14 +50,12 @@ type AuthoringSessionData =
       session?: null;
     };
 
-const validateAuthoringSessionQueryRef = makeFunctionReference<
-  "query",
+const validateAuthoringSessionQueryRef = widgetQueryRef<
   { token: string },
   AuthoringSessionData | null
 >("authoringSessions:validate");
 
-const updateAuthoringStepMutationRef = makeFunctionReference<
-  "mutation",
+const updateAuthoringStepMutationRef = widgetMutationRef<
   {
     token: string;
     stepId: Id<"tourSteps">;
@@ -64,14 +66,12 @@ const updateAuthoringStepMutationRef = makeFunctionReference<
   null
 >("authoringSessions:updateStep");
 
-const setAuthoringCurrentStepMutationRef = makeFunctionReference<
-  "mutation",
+const setAuthoringCurrentStepMutationRef = widgetMutationRef<
   { token: string; stepId: Id<"tourSteps"> },
   null
 >("authoringSessions:setCurrentStep");
 
-const endAuthoringSessionMutationRef = makeFunctionReference<
-  "mutation",
+const endAuthoringSessionMutationRef = widgetMutationRef<
   { token: string },
   null
 >("authoringSessions:end");
@@ -184,12 +184,12 @@ export function AuthoringOverlay({ token, onExit }: AuthoringOverlayProps) {
   );
   const overlayRef = useRef<HTMLDivElement>(null);
 
-  const sessionData = useQuery(validateAuthoringSessionQueryRef, { token }) as
+  const sessionData = useWidgetQuery(validateAuthoringSessionQueryRef, { token }) as
     | AuthoringSessionData
     | undefined;
-  const updateStepMutation = useMutation(updateAuthoringStepMutationRef);
-  const setCurrentStepMutation = useMutation(setAuthoringCurrentStepMutationRef);
-  const endSessionMutation = useMutation(endAuthoringSessionMutationRef);
+  const updateStepMutation = useWidgetMutation(updateAuthoringStepMutationRef);
+  const setCurrentStepMutation = useWidgetMutation(setAuthoringCurrentStepMutationRef);
+  const endSessionMutation = useWidgetMutation(endAuthoringSessionMutationRef);
 
   const steps = useMemo(
     () => (sessionData?.valid ? (sessionData.steps ?? []) : []),

apps/widget/src/ChecklistOverlay.tsx

@@ -1,9 +1,13 @@
 import { useState, useCallback } from "react";
-import { useQuery, useMutation } from "convex/react";
-import { makeFunctionReference } from "convex/server";
 import { CheckSquare, ChevronDown, ChevronUp, ExternalLink } from "./icons";
 import type { Id } from "@opencom/convex/dataModel";
 import { safeOpenUrl } from "./utils/safeOpenUrl";
+import {
+  useWidgetMutation,
+  useWidgetQuery,
+  widgetMutationRef,
+  widgetQueryRef,
+} from "./lib/convex/hooks";
 
 interface ChecklistTask {
   id: string;
@@ -37,14 +41,12 @@ type EligibleChecklistRecord = {
   progress: { completedTaskIds: string[] } | null;
 };
 
-const eligibleChecklistsQueryRef = makeFunctionReference<
-  "query",
+const eligibleChecklistsQueryRef = widgetQueryRef<
   { workspaceId: Id<"workspaces">; visitorId: Id<"visitors">; sessionToken?: string },
   EligibleChecklistRecord[]
 >("checklists:getEligible");
 
-const completeChecklistTaskMutationRef = makeFunctionReference<
-  "mutation",
+const completeChecklistTaskMutationRef = widgetMutationRef<
   {
     visitorId: Id<"visitors">;
     checklistId: Id<"checklists">;
@@ -55,8 +57,7 @@ const completeChecklistTaskMutationRef = makeFunctionReference<
   null
 >("checklists:completeTask");
 
-const uncompleteChecklistTaskMutationRef = makeFunctionReference<
-  "mutation",
+const uncompleteChecklistTaskMutationRef = widgetMutationRef<
   {
     visitorId: Id<"visitors">;
     checklistId: Id<"checklists">;
@@ -75,14 +76,14 @@ export function ChecklistOverlay({
 }: ChecklistOverlayProps) {
   const [expandedChecklist, setExpandedChecklist] = useState<Id<"checklists"> | null>(null);
 
-  const eligibleChecklists = useQuery(eligibleChecklistsQueryRef, {
+  const eligibleChecklists = useWidgetQuery(eligibleChecklistsQueryRef, {
     workspaceId,
     visitorId,
     sessionToken: sessionToken ?? undefined,
   }) as EligibleChecklistRecord[] | undefined;
 
-  const completeTask = useMutation(completeChecklistTaskMutationRef);
-  const uncompleteTask = useMutation(uncompleteChecklistTaskMutationRef);
+  const completeTask = useWidgetMutation(completeChecklistTaskMutationRef);
+  const uncompleteTask = useWidgetMutation(uncompleteChecklistTaskMutationRef);
 
   const handleTaskClick = useCallback(
     async (checklist: Checklist, task: ChecklistTask, isCompleted: boolean) => {

apps/widget/src/CsatPrompt.tsx

@@ -1,11 +1,9 @@
 import { useState } from "react";
-import { useMutation } from "convex/react";
-import { makeFunctionReference } from "convex/server";
 import { X } from "./icons";
 import type { Id } from "@opencom/convex/dataModel";
+import { useWidgetMutation, widgetMutationRef } from "./lib/convex/hooks";
 
-const submitCsatResponseMutationRef = makeFunctionReference<
-  "mutation",
+const submitCsatResponseMutationRef = widgetMutationRef<
   {
     conversationId: Id<"conversations">;
     rating: number;
@@ -37,7 +35,7 @@ export function CsatPrompt({
   const [submitted, setSubmitted] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  const submitCsat = useMutation(submitCsatResponseMutationRef);
+  const submitCsat = useWidgetMutation(submitCsatResponseMutationRef);
 
   const handleSubmit = async () => {
     if (rating === null) return;

apps/widget/src/OutboundOverlay.tsx

@@ -1,13 +1,17 @@
 import { useState, useEffect, useCallback, useRef, useMemo, type MouseEvent } from "react";
-import { useQuery, useMutation } from "convex/react";
-import { makeFunctionReference } from "convex/server";
 import { X } from "./icons";
 import type { Id } from "@opencom/convex/dataModel";
 import type {
   EligibleOutboundMessage,
   OutboundClickAction,
 } from "@opencom/types";
 import { safeOpenUrl } from "./utils/safeOpenUrl";
+import {
+  useWidgetMutation,
+  useWidgetQuery,
+  widgetMutationRef,
+  widgetQueryRef,
+} from "./lib/convex/hooks";
 
 type ClickAction = OutboundClickAction<Id<"articles">>;
 type OutboundMessage = EligibleOutboundMessage<
@@ -17,8 +21,7 @@ type OutboundMessage = EligibleOutboundMessage<
   Id<"articles">
 >;
 
-const eligibleOutboundMessagesQueryRef = makeFunctionReference<
-  "query",
+const eligibleOutboundMessagesQueryRef = widgetQueryRef<
   {
     workspaceId: Id<"workspaces">;
     visitorId: Id<"visitors">;
@@ -29,8 +32,7 @@ const eligibleOutboundMessagesQueryRef = makeFunctionReference<
   OutboundMessage[]
 >("outboundMessages:getEligible");
 
-const trackOutboundImpressionMutationRef = makeFunctionReference<
-  "mutation",
+const trackOutboundImpressionMutationRef = widgetMutationRef<
   {
     messageId: Id<"outboundMessages">;
     visitorId: Id<"visitors">;
@@ -97,15 +99,15 @@ export function OutboundOverlay({
   const [timeOnPage, setTimeOnPage] = useState(0);
   const staggerTimers = useRef<ReturnType<typeof setTimeout>[]>([]);
 
-  const eligibleMessages = useQuery(eligibleOutboundMessagesQueryRef, {
+  const eligibleMessages = useWidgetQuery(eligibleOutboundMessagesQueryRef, {
     workspaceId,
     visitorId,
     sessionToken: sessionToken ?? undefined,
     currentUrl,
     sessionId,
   }) as OutboundMessage[] | undefined;
 
-  const trackImpression = useMutation(trackOutboundImpressionMutationRef);
+  const trackImpression = useWidgetMutation(trackOutboundImpressionMutationRef);
 
   // Track scroll depth
   useEffect(() => {

apps/widget/src/SurveyOverlay.tsx

@@ -1,16 +1,14 @@
 import { useState, useEffect } from "react";
-import { useMutation } from "convex/react";
-import { makeFunctionReference } from "convex/server";
 import { normalizeSurveyAnswerValue } from "./surveyOverlay/answers";
 import {
   LargeFormatContainer,
   SmallFormatContainer,
   SurveyQuestionRenderer,
 } from "./surveyOverlay/components";
 import type { SurveyOverlayProps } from "./surveyOverlay/types";
+import { useWidgetMutation, widgetMutationRef } from "./lib/convex/hooks";
 
-const submitSurveyResponseMutationRef = makeFunctionReference<
-  "mutation",
+const submitSurveyResponseMutationRef = widgetMutationRef<
   {
     surveyId: string;
     visitorId: string;
@@ -22,8 +20,7 @@ const submitSurveyResponseMutationRef = makeFunctionReference<
   null
 >("surveys:submitResponse");
 
-const recordSurveyImpressionMutationRef = makeFunctionReference<
-  "mutation",
+const recordSurveyImpressionMutationRef = widgetMutationRef<
   {
     surveyId: string;
     visitorId: string;
@@ -48,8 +45,8 @@ export function SurveyOverlay({
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [showThankYou, setShowThankYou] = useState(false);
 
-  const submitResponse = useMutation(submitSurveyResponseMutationRef);
-  const recordImpression = useMutation(recordSurveyImpressionMutationRef);
+  const submitResponse = useWidgetMutation(submitSurveyResponseMutationRef);
+  const recordImpression = useWidgetMutation(recordSurveyImpressionMutationRef);
 
   const totalSteps = survey.questions.length;
   const isIntroStep = currentStep === -1;

apps/widget/src/TooltipAuthoringOverlay.tsx

@@ -1,10 +1,14 @@
 import { useState, useEffect, useCallback, useRef } from "react";
-import { useQuery, useMutation } from "convex/react";
-import { makeFunctionReference } from "convex/server";
 import { scoreSelectorQuality, type SelectorQualityMetadata } from "@opencom/sdk-core";
 import type { Id } from "@opencom/convex/dataModel";
 import { normalizeUnknownError, type ErrorFeedbackMessage } from "@opencom/web-shared";
 import { ErrorFeedbackBanner } from "./components/ErrorFeedbackBanner";
+import {
+  useWidgetMutation,
+  useWidgetQuery,
+  widgetMutationRef,
+  widgetQueryRef,
+} from "./lib/convex/hooks";
 
 interface TooltipAuthoringOverlayProps {
   token: string;
@@ -34,14 +38,12 @@ type TooltipSessionData =
       tooltip?: null;
     };
 
-const validateTooltipAuthoringSessionQueryRef = makeFunctionReference<
-  "query",
+const validateTooltipAuthoringSessionQueryRef = widgetQueryRef<
   { token: string; workspaceId: Id<"workspaces"> },
   TooltipSessionData | null
 >("tooltipAuthoringSessions:validate");
 
-const updateTooltipSelectorMutationRef = makeFunctionReference<
-  "mutation",
+const updateTooltipSelectorMutationRef = widgetMutationRef<
   {
     token: string;
     workspaceId: Id<"workspaces">;
@@ -51,8 +53,7 @@ const updateTooltipSelectorMutationRef = makeFunctionReference<
   null
 >("tooltipAuthoringSessions:updateSelector");
 
-const endTooltipAuthoringSessionMutationRef = makeFunctionReference<
-  "mutation",
+const endTooltipAuthoringSessionMutationRef = widgetMutationRef<
   { token: string; workspaceId: Id<"workspaces"> },
   null
 >("tooltipAuthoringSessions:end");
@@ -142,11 +143,14 @@ export function TooltipAuthoringOverlay({
   );
   const overlayRef = useRef<HTMLDivElement>(null);
 
-  const sessionData = useQuery(validateTooltipAuthoringSessionQueryRef, { token, workspaceId }) as
+  const sessionData = useWidgetQuery(validateTooltipAuthoringSessionQueryRef, {
+    token,
+    workspaceId,
+  }) as
     | TooltipSessionData
     | undefined;
-  const updateSelectorMutation = useMutation(updateTooltipSelectorMutationRef);
-  const endSessionMutation = useMutation(endTooltipAuthoringSessionMutationRef);
+  const updateSelectorMutation = useWidgetMutation(updateTooltipSelectorMutationRef);
+  const endSessionMutation = useWidgetMutation(endTooltipAuthoringSessionMutationRef);
 
   const tooltip = sessionData?.valid ? sessionData.tooltip : null;