@kasuvia/sdk 0.0.8 → 0.0.9

package/src/hooks/use-customer-address.ts

@@ -0,0 +1,64 @@
+/**
+ * Customer Saved-Address Book Hooks
+ */
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import {
+  getCustomerAddresses,
+  createCustomerAddress,
+  updateCustomerAddress,
+  deleteCustomerAddress,
+} from '../services/auth.service'
+import type { CreateCustomerAddressPayload, UpdateCustomerAddressPayload } from '../types/auth'
+import type { SdkConfig } from '../config'
+import { useSdkContext, resolveHookArgs } from '../context/sdk-context'
+
+const ADDRESSES_QUERY_KEY = 'customer-addresses'
+
+export function useCustomerAddresses(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  return useQuery({
+    queryKey: [ADDRESSES_QUERY_KEY, token],
+    queryFn: () => token ? getCustomerAddresses(cfg, token) : Promise.reject(new Error('No access token available')),
+    enabled: !!token,
+  })
+}
+
+export function useCreateCustomerAddress(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (payload: CreateCustomerAddressPayload) =>
+      token ? createCustomerAddress(cfg, token, payload) : Promise.reject(new Error('Please sign in to save an address.')),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [ADDRESSES_QUERY_KEY] })
+    },
+  })
+}
+
+export function useUpdateCustomerAddress(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: ({ addressId, payload }: { addressId: string; payload: UpdateCustomerAddressPayload }) =>
+      token ? updateCustomerAddress(cfg, token, addressId, payload) : Promise.reject(new Error('Please sign in to update this address.')),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [ADDRESSES_QUERY_KEY] })
+    },
+  })
+}
+
+export function useDeleteCustomerAddress(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (addressId: string) =>
+      token ? deleteCustomerAddress(cfg, token, addressId) : Promise.reject(new Error('Please sign in to remove this address.')),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [ADDRESSES_QUERY_KEY] })
+    },
+  })
+}

package/src/hooks/use-feedback.ts

@@ -0,0 +1,34 @@
+/**
+ * Feedback Hooks
+ */
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { createFeedback, getMyFeedback, type CreateFeedbackParams } from '../services/feedback.service'
+import type { SdkConfig } from '../config'
+import { useSdkContext, resolveHookArgs } from '../context/sdk-context'
+
+export function useCreateFeedback(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (params: CreateFeedbackParams) =>
+      token ? createFeedback(cfg, token, params) : Promise.reject(new Error('Please sign in to submit a message.')),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['my-feedback'] })
+    },
+  })
+}
+
+export function useMyFeedback(
+  params?: { page?: number; page_size?: number },
+  config?: SdkConfig,
+  accessToken?: string | null
+) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  return useQuery({
+    queryKey: ['my-feedback', token, params],
+    queryFn: () => token ? getMyFeedback(cfg, token, params) : Promise.reject(new Error('No access token available')),
+    enabled: !!token,
+  })
+}

package/src/hooks/use-languages.ts

@@ -7,47 +7,34 @@ import { useSdkContext, resolveHookArgs } from '../context/sdk-context'
 
 export async function getSupportedLanguagesList(config: SdkConfig): Promise<SupportedLang[]> {
   const data = await getSupportedLanguages(config)
-  return (data.languages || []).map((language: BackendLanguage) => ({
-    code: language.code,
-    appCode: language.code,
-    label: language.label,
-    native: language.label,
-    flag: language.flag,
-  }))
+  return (data.languages || [])
+    .filter((language: BackendLanguage) => language.code !== 'auto')
+    .map((language: BackendLanguage) => ({
+      code: language.code,
+      appCode: language.code,
+      label: language.label,
+      native: language.label,
+      flag: language.flag,
+    }))
 }
 
 export function useSupportedLanguages(config?: SdkConfig): UseQueryResult<SupportedLang[], Error> {
   const ctx = useSdkContext()
-  try {
-    const { config: cfg } = resolveHookArgs(config, undefined, ctx)
-    return useQuery({
-      queryKey: ['supported-languages'],
-      queryFn: () => getSupportedLanguagesList(cfg),
-      retry: 1,
-      ...getCacheTier('high'),
-    });
-  } catch {
-    return {
-      data: [],
-      isLoading: false,
-      error: null,
-      isFetching: false,
-      isPending: false,
-      isError: false,
-      isSuccess: true,
-      status: 'success',
-      fetchStatus: 'idle',
-      refetch: async () => ({
-        data: [],
-        isLoading: false,
-        error: null,
-        isFetching: false,
-        isPending: false,
-        isError: false,
-        isSuccess: true,
-        status: 'success',
-        fetchStatus: 'idle',
-      } as unknown as UseQueryResult<SupportedLang[], Error>),
-    } as unknown as UseQueryResult<SupportedLang[], Error>;
-  }
+  // REAL BUG FIXED (2026-09-22): wrapping resolveHookArgs (and the useQuery
+  // call itself) in try/catch swallowed the ONE thing that can actually
+  // throw here — a missing SdkConfig/SdkProvider, resolveHookArgs' own
+  // deliberate, explicit failure — into a fabricated `{ data: [], isSuccess:
+  // true, status: 'success' }`. A caller would read that as "this business
+  // genuinely has zero supported languages," not "the SDK isn't wired up,"
+  // hiding a real integration bug behind a fake successful empty state.
+  // Also called useQuery conditionally inside a try block, which the Rules
+  // of Hooks forbid. No other hook in this SDK catches resolveHookArgs;
+  // this one shouldn't either.
+  const { config: cfg } = resolveHookArgs(config, undefined, ctx)
+  return useQuery({
+    queryKey: ['supported-languages', cfg.businessId],
+    queryFn: () => getSupportedLanguagesList(cfg),
+    retry: 1,
+    ...getCacheTier('high'),
+  });
 }

package/src/hooks/use-media-upload.ts

@@ -0,0 +1,23 @@
+/**
+ * Media Upload Hook
+ *
+ * Wraps media.service.ts's uploadMediaFile/uploadMediaFiles (the real
+ * presign → PUT → confirm sequence) as a React Query mutation. No SdkConfig
+ * or access token is needed here — the two proxy routes it calls read the
+ * customer's session cookie server-side.
+ */
+import { useMutation } from '@tanstack/react-query'
+import { uploadMediaFile, uploadMediaFiles, type UploadMediaFileParams } from '../services/media.service'
+
+export function useUploadMediaFile() {
+  return useMutation({
+    mutationFn: (params: UploadMediaFileParams) => uploadMediaFile(params),
+  })
+}
+
+export function useUploadMediaFiles() {
+  return useMutation({
+    mutationFn: ({ files, ...params }: Omit<UploadMediaFileParams, 'file'> & { files: File[] }) =>
+      uploadMediaFiles(files, params),
+  })
+}

package/src/hooks/use-notification-stream.ts

@@ -0,0 +1,88 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { fetchEventSource, EventSourceMessage } from '@microsoft/fetch-event-source';
+import type { SdkConfig } from '../config';
+import { logger } from '../utils';
+import { useSdkContext } from '../context/sdk-context';
+
+interface NotificationStreamMessage {
+  type: string;
+  title?: string;
+  body?: string;
+  data?: Record<string, unknown>;
+  timestamp?: string;
+}
+
+export interface UseNotificationStreamOptions {
+  config?: SdkConfig;
+  accessToken?: string | null;
+  onNotification?: (message: NotificationStreamMessage) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Live connection to the authenticated customer's real-time notification
+ * stream (kasuvia-notification-system-go's /notifications/sse — now
+ * Authorization-header-gated, see realtime.go's 2026-09-21 fix). Mirrors
+ * use-order-stream.ts's proven fetch-event-source pattern exactly.
+ */
+export function useNotificationStream({
+  config: explicitConfig,
+  accessToken: explicitToken,
+  onNotification,
+  onError,
+}: UseNotificationStreamOptions) {
+  const ctx = useSdkContext();
+  const config = explicitConfig ?? ctx?.config;
+  const accessToken = explicitToken !== undefined ? explicitToken : (ctx?.accessToken ?? null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    if (!accessToken || !config) {
+      return;
+    }
+
+    const abortController = new AbortController();
+    abortControllerRef.current = abortController;
+
+    const streamUrl = `${config.backendUrls.notifications}/notifications/sse`;
+
+    fetchEventSource(streamUrl, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${accessToken}` },
+      signal: abortController.signal,
+      openWhenHidden: true,
+      onopen: async (response) => {
+        if (response.ok) {
+          logger.log('[NotificationStream] Connection established');
+          return;
+        }
+        throw new Error(`Unexpected response: ${response.status}`);
+      },
+      onmessage: (event: EventSourceMessage) => {
+        try {
+          if (!event.data || event.data.trim() === '') return;
+          const data = JSON.parse(event.data) as NotificationStreamMessage;
+          if (data.type === 'connected') return; // handshake frame, not a real notification
+          logger.log('[NotificationStream] Received:', data);
+          onNotification?.(data);
+        } catch (error) {
+          logger.error('[NotificationStream] Error parsing event:', error);
+        }
+      },
+      onerror: (error: Error) => {
+        if (abortController.signal.aborted) return;
+        logger.error('[NotificationStream] Connection error:', error);
+        onError?.(error);
+      },
+    }).catch((error) => {
+      if (abortController.signal.aborted || error.name === 'AbortError') return;
+      logger.error('[NotificationStream] fetchEventSource failed:', error);
+    });
+
+    return () => {
+      abortController.abort();
+    };
+  }, [accessToken, config, onNotification, onError]);
+}

package/src/hooks/use-notifications.ts

@@ -0,0 +1,163 @@
+/**
+ * Notification Preference Hooks
+ *
+ * React Query hooks for notification channel preferences — both the
+ * caller's own self-service preferences (customer or business owner) and
+ * the merchant-level channel policy (owner-only).
+ * Stateless - requires config + accessToken.
+ */
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import {
+  getNotificationPreferences,
+  updateNotificationPreferences,
+  sendContactEmail,
+  sendContactConfirmation,
+  getVapidPublicKey,
+  subscribeToPush,
+  unsubscribeFromPush,
+  getNotificationInbox,
+  markNotificationRead,
+  markAllNotificationsRead,
+  trackNotificationClick,
+  type ContactFormData,
+  type SubscribeToPushParams,
+} from '../services/notifications.service'
+import type { NotificationPreferences } from '../types/auth'
+import type { SdkConfig } from '../config'
+import { useSdkContext, resolveHookArgs } from '../context/sdk-context'
+import { logger } from '../utils/logger'
+
+export function useNotificationPreferences(config?: SdkConfig, accessToken?: string) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken ?? null, ctx)
+  return useQuery({
+    queryKey: ['notification-preferences'],
+    queryFn: () => getNotificationPreferences(cfg, token ?? ''),
+    enabled: !!token,
+  })
+}
+
+export function useUpdateNotificationPreferences(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (payload: Partial<NotificationPreferences>) =>
+      token ? updateNotificationPreferences(cfg, token, payload) : Promise.reject(new Error('No access token available')),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['notification-preferences'] })
+    },
+  })
+}
+
+// ── Push subscriptions ───────────────────────────────────────────────────
+
+export function useVapidPublicKey(config?: SdkConfig) {
+  const ctx = useSdkContext()
+  const { config: cfg } = resolveHookArgs(config, null, ctx)
+  return useQuery({
+    queryKey: ['vapid-public-key'],
+    queryFn: () => getVapidPublicKey(cfg),
+    staleTime: Infinity,
+  })
+}
+
+export function useSubscribeToPush(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  return useMutation({
+    mutationFn: (params: SubscribeToPushParams) =>
+      token ? subscribeToPush(cfg, token, params) : Promise.reject(new Error('Please sign in to enable push notifications.')),
+  })
+}
+
+export function useUnsubscribeFromPush(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  return useMutation({
+    mutationFn: (endpoint: string) =>
+      token ? unsubscribeFromPush(cfg, token, endpoint) : Promise.reject(new Error('No access token available')),
+  })
+}
+
+// ── Notification inbox ──────────────────────────────────────────────────
+
+export function useNotificationInbox(
+  params?: { page?: number; limit?: number; unread_only?: boolean },
+  config?: SdkConfig,
+  accessToken?: string | null
+) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  return useQuery({
+    queryKey: ['notification-inbox', token, params],
+    queryFn: () => token ? getNotificationInbox(cfg, token, params) : Promise.reject(new Error('No access token available')),
+    enabled: !!token,
+  })
+}
+
+export function useMarkNotificationRead(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (notificationId: string) =>
+      token ? markNotificationRead(cfg, token, notificationId) : Promise.reject(new Error('No access token available')),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['notification-inbox'] })
+    },
+  })
+}
+
+export function useMarkAllNotificationsRead(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: () =>
+      token ? markAllNotificationsRead(cfg, token) : Promise.reject(new Error('No access token available')),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['notification-inbox'] })
+    },
+  })
+}
+
+export function useTrackNotificationClick(config?: SdkConfig, accessToken?: string | null) {
+  const ctx = useSdkContext()
+  const { config: cfg, accessToken: token } = resolveHookArgs(config, accessToken, ctx)
+  return useMutation({
+    mutationFn: (notificationId: string) =>
+      token ? trackNotificationClick(cfg, token, notificationId) : Promise.reject(new Error('No access token available')),
+  })
+}
+
+/**
+ * Submit contact form hook — sends contact email to merchant and confirmation to sender.
+ */
+export function useSubmitContactForm(config?: SdkConfig) {
+  const ctx = useSdkContext()
+  const { config: cfg } = resolveHookArgs(config, null, ctx)
+  return useMutation({
+    mutationFn: async (payload: ContactFormData) => {
+      // REAL BUG FIXED (2026-09-22): defaulted a missing `source` to the
+      // literal string 'kasuvia-storefront' — a specific app name hardcoded
+      // into a package meant to be reused by other storefronts too. A
+      // different consuming app that forgot to pass `source` would have its
+      // contact-form submissions silently mislabeled as coming from an app
+      // it isn't. The caller decides what `source` means; not passing one
+      // is left as-is rather than guessed.
+      const emailPayload = {
+        ...payload,
+        current_year: new Date().getFullYear(),
+      }
+      const res = await sendContactEmail(cfg, emailPayload)
+      try {
+        await sendContactConfirmation(cfg, emailPayload)
+      } catch (confirmError) {
+        logger.error('[useSubmitContactForm] Failed to send confirmation email:', confirmError)
+      }
+      return res
+    },
+  })
+}
+

package/src/hooks/use-order-stream.ts

@@ -17,6 +17,16 @@ interface PaymentSuccessData {
   };
 }
 
+interface PaymentFailedData {
+  event: string;
+  data: {
+    transaction_id: string;
+    order_id: string;
+    status: string;
+    gateway: string;
+  };
+}
+
 interface DigitalReadyData {
   event: string;
   data: {
@@ -47,18 +57,6 @@ interface BespokeUpdateData {
   };
 }
 
-interface ConsultationUpdateData {
-  event: string;
-  data: {
-    consultation_id: string;
-    business_id: string;
-    customer_id: string;
-    status: string;
-    message?: string;
-    updated_at: string;
-  };
-}
-
 interface ServiceBookingUpdateData {
   event: string;
   data: {
@@ -76,22 +74,23 @@ export interface UseOrderStreamOptions {
   config?: SdkConfig;
   orderId: string;
   onPaymentComplete?: (data: PaymentSuccessData) => void;
+  /** Fires on a real "payment.failed" event from the order-scoped stream (kasuvia-payment-system-go's webhook services now publish this — see monnify_webhook_service.go/flutterwave_webhook_service.go). */
+  onPaymentFailed?: (data: PaymentFailedData) => void;
   onDigitalReady?: (data: DigitalReadyData) => void;
   onBespokeUpdate?: (data: BespokeUpdateData) => void;
-  onConsultationUpdate?: (data: ConsultationUpdateData) => void;
   onServiceBookingUpdate?: (data: ServiceBookingUpdateData) => void;
   onError?: (error: Error) => void;
 }
 
-export function useOrderStream({ 
+export function useOrderStream({
   config: explicitConfig,
-  orderId, 
-  onPaymentComplete, 
-  onDigitalReady, 
-  onBespokeUpdate, 
-  onConsultationUpdate, 
-  onServiceBookingUpdate, 
-  onError 
+  orderId,
+  onPaymentComplete,
+  onPaymentFailed,
+  onDigitalReady,
+  onBespokeUpdate,
+  onServiceBookingUpdate,
+  onError
 }: UseOrderStreamOptions) {
   const ctx = useSdkContext();
   const config = explicitConfig ?? ctx?.config;
@@ -127,6 +126,14 @@ export function useOrderStream({
             abortController.abort();
           }
 
+          if (data.event === 'payment.failed') {
+            logger.log('[OrderStream] Payment failed detected, calling onPaymentFailed');
+            if (onPaymentFailed) {
+              onPaymentFailed(data as PaymentFailedData);
+            }
+            abortController.abort();
+          }
+
           if (data.event === 'digital.ready') {
             logger.log('[OrderStream] Digital delivery ready detected, calling onDigitalReady');
             if (onDigitalReady) {
@@ -141,13 +148,6 @@ export function useOrderStream({
             }
           }
 
-          if (data.event === 'consultation.update') {
-            logger.log('[OrderStream] Consultation update detected, calling onConsultationUpdate');
-            if (onConsultationUpdate) {
-              onConsultationUpdate(data as ConsultationUpdateData);
-            }
-          }
-
           if (data.event === 'service_booking.update') {
             logger.log('[OrderStream] Service booking update detected, calling onServiceBookingUpdate');
             if (onServiceBookingUpdate) {
@@ -193,7 +193,7 @@ export function useOrderStream({
     return () => {
       abortController.abort();
     };
-  }, [orderId, onPaymentComplete, onDigitalReady, onBespokeUpdate, onConsultationUpdate, onServiceBookingUpdate, onError]);
+  }, [orderId, onPaymentComplete, onPaymentFailed, onDigitalReady, onBespokeUpdate, onServiceBookingUpdate, onError]);
 
   return null;
 }