@harkenapp/sdk-react-native 0.0.1-alpha.1 → 0.0.1-alpha.2

package/src/hooks/useAttachmentUpload.ts

@@ -5,13 +5,14 @@
  * Uploads happen in background via the singleton uploadQueueService.
  */
 
-import { useState, useEffect, useCallback, useRef } from 'react';
-import * as ImagePicker from 'expo-image-picker';
-import * as DocumentPicker from 'expo-document-picker';
-import * as FileSystem from 'expo-file-system/legacy';
-import { uploadQueueService } from '../services';
-import { UploadPhase, UploadProgress } from '../domain';
-import { useHarkenContext } from './useHarkenContext';
+import { useState, useEffect, useCallback, useRef } from "react";
+import * as ImagePicker from "expo-image-picker";
+import * as DocumentPicker from "expo-document-picker";
+import * as FileSystem from "expo-file-system/legacy";
+import { uploadQueueService } from "../services";
+import type { UploadProgress } from "../domain";
+import { UploadPhase } from "../domain";
+import { useHarkenContext } from "./useHarkenContext";
 
 /**
  * State for a single attachment.
@@ -41,7 +42,7 @@ export interface UseAttachmentUploadResult {
   attachments: AttachmentState[];
 
   /** Pick image from camera or library */
-  pickImage: (source: 'camera' | 'library') => Promise<AttachmentState | null>;
+  pickImage: (source: "camera" | "library") => Promise<AttachmentState | null>;
 
   /** Pick document (images or PDFs) */
   pickDocument: () => Promise<AttachmentState | null>;
@@ -118,9 +119,7 @@ export interface UseAttachmentUploadResult {
  */
 export function useAttachmentUpload(): UseAttachmentUploadResult {
   const { client, config } = useHarkenContext();
-  const [attachments, setAttachments] = useState<Map<string, AttachmentState>>(
-    new Map()
-  );
+  const [attachments, setAttachments] = useState<Map<string, AttachmentState>>(new Map());
 
   // Track which attachment IDs this hook instance is managing
   const attachmentIdsRef = useRef<Set<string>>(new Set());
@@ -142,26 +141,24 @@ export function useAttachmentUpload(): UseAttachmentUploadResult {
       return;
     }
 
-    const unsubProgress = uploadQueueService.onProgress(
-      (progress: UploadProgress) => {
-        // Only track attachments we added
-        if (!attachmentIdsRef.current.has(progress.attachmentId)) return;
-
-        setAttachments((prev) => {
-          const existing = prev.get(progress.attachmentId);
-          if (!existing) return prev;
-
-          const next = new Map(prev);
-          next.set(progress.attachmentId, {
-            ...existing,
-            phase: progress.phase,
-            progress: progress.progress,
-            error: progress.error,
-          });
-          return next;
+    const unsubProgress = uploadQueueService.onProgress((progress: UploadProgress) => {
+      // Only track attachments we added
+      if (!attachmentIdsRef.current.has(progress.attachmentId)) return;
+
+      setAttachments((prev) => {
+        const existing = prev.get(progress.attachmentId);
+        if (!existing) return prev;
+
+        const next = new Map(prev);
+        next.set(progress.attachmentId, {
+          ...existing,
+          phase: progress.phase,
+          progress: progress.progress,
+          error: progress.error,
         });
-      }
-    );
+        return next;
+      });
+    });
 
     return () => {
       unsubProgress();
@@ -206,14 +203,14 @@ export function useAttachmentUpload(): UseAttachmentUploadResult {
    * Pick an image from camera or photo library.
    */
   const pickImage = useCallback(
-    async (source: 'camera' | 'library'): Promise<AttachmentState | null> => {
+    async (source: "camera" | "library"): Promise<AttachmentState | null> => {
       const options: ImagePicker.ImagePickerOptions = {
-        mediaTypes: ['images'],
+        mediaTypes: ["images"],
         quality: 0.8,
       };
 
       const result =
-        source === 'camera'
+        source === "camera"
           ? await ImagePicker.launchCameraAsync(options)
           : await ImagePicker.launchImageLibraryAsync(options);
 
@@ -223,7 +220,7 @@ export function useAttachmentUpload(): UseAttachmentUploadResult {
 
       const asset = result.assets[0];
       const fileName = asset.fileName ?? `image_${Date.now()}.jpg`;
-      const mimeType = asset.mimeType ?? 'image/jpeg';
+      const mimeType = asset.mimeType ?? "image/jpeg";
 
       // Get file size - use asset.fileSize if available, otherwise query filesystem
       let fileSize = asset.fileSize;
@@ -247,7 +244,7 @@ export function useAttachmentUpload(): UseAttachmentUploadResult {
    */
   const pickDocument = useCallback(async (): Promise<AttachmentState | null> => {
     const result = await DocumentPicker.getDocumentAsync({
-      type: ['image/*', 'application/pdf'],
+      type: ["image/*", "application/pdf"],
       copyToCacheDirectory: true,
     });
 
@@ -266,7 +263,7 @@ export function useAttachmentUpload(): UseAttachmentUploadResult {
 
     return addAttachment({
       uri: asset.uri,
-      mimeType: asset.mimeType ?? 'application/octet-stream',
+      mimeType: asset.mimeType ?? "application/octet-stream",
       fileName: asset.name,
       fileSize,
     });
@@ -275,28 +272,22 @@ export function useAttachmentUpload(): UseAttachmentUploadResult {
   /**
    * Retry a failed attachment upload.
    */
-  const retryAttachment = useCallback(
-    async (attachmentId: string): Promise<void> => {
-      await uploadQueueService.retryItem(attachmentId);
-    },
-    []
-  );
+  const retryAttachment = useCallback(async (attachmentId: string): Promise<void> => {
+    await uploadQueueService.retryItem(attachmentId);
+  }, []);
 
   /**
    * Remove an attachment (cancels upload if in progress).
    */
-  const removeAttachment = useCallback(
-    async (attachmentId: string): Promise<void> => {
-      await uploadQueueService.cancelItem(attachmentId);
-      attachmentIdsRef.current.delete(attachmentId);
-      setAttachments((prev) => {
-        const next = new Map(prev);
-        next.delete(attachmentId);
-        return next;
-      });
-    },
-    []
-  );
+  const removeAttachment = useCallback(async (attachmentId: string): Promise<void> => {
+    await uploadQueueService.cancelItem(attachmentId);
+    attachmentIdsRef.current.delete(attachmentId);
+    setAttachments((prev) => {
+      const next = new Map(prev);
+      next.delete(attachmentId);
+      return next;
+    });
+  }, []);
 
   /**
    * Get all attachment IDs for feedback submission.

package/src/hooks/useFeedback.test.ts

@@ -0,0 +1,376 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { useFeedback } from "./useFeedback";
+import { HarkenApiError, HarkenNetworkError } from "../api/errors";
+import type { FeedbackCategory } from "../types";
+
+// Mock dependencies
+vi.mock("react-native", () => ({
+  Platform: { OS: "ios" },
+}));
+
+const mockSubmitFeedback = vi.fn();
+
+vi.mock("../api/client", () => ({
+  HarkenClient: class MockHarkenClient {
+    submitFeedback = mockSubmitFeedback;
+  },
+}));
+
+vi.mock("./useHarkenContext", () => ({
+  useHarkenContext: vi.fn(() => ({
+    config: {
+      publishableKey: "pk_test_123",
+      userToken: undefined,
+      apiBaseUrl: "https://api.harken.app",
+    },
+  })),
+}));
+
+import { useAnonymousId } from "./useAnonymousId";
+
+vi.mock("./useAnonymousId", () => ({
+  useAnonymousId: vi.fn(() => ({
+    anonymousId: "test-anon-id-123",
+    isLoading: false,
+  })),
+}));
+
+describe("useFeedback", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("payload construction", () => {
+    it("sends correct payload to client", async () => {
+      mockSubmitFeedback.mockResolvedValue({ id: "feedback_123" });
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        await result.current.submitFeedback({
+          message: "Great app!",
+          category: "idea" as FeedbackCategory,
+        });
+      });
+
+      expect(mockSubmitFeedback).toHaveBeenCalledWith({
+        message: "Great app!",
+        category: "idea",
+        title: undefined,
+        anon_id: "test-anon-id-123",
+        metadata: { platform: "ios" },
+        attachments: undefined,
+      });
+    });
+
+    it("includes title when provided", async () => {
+      mockSubmitFeedback.mockResolvedValue({ id: "feedback_123" });
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        await result.current.submitFeedback({
+          message: "Bug description",
+          category: "bug" as FeedbackCategory,
+          title: "Login issue",
+        });
+      });
+
+      expect(mockSubmitFeedback).toHaveBeenCalledWith(
+        expect.objectContaining({
+          title: "Login issue",
+        })
+      );
+    });
+
+    it("includes attachments when provided", async () => {
+      mockSubmitFeedback.mockResolvedValue({ id: "feedback_123" });
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        await result.current.submitFeedback({
+          message: "See attached screenshot",
+          category: "bug" as FeedbackCategory,
+          attachments: ["att_123", "att_456"],
+        });
+      });
+
+      expect(mockSubmitFeedback).toHaveBeenCalledWith(
+        expect.objectContaining({
+          attachments: ["att_123", "att_456"],
+        })
+      );
+    });
+
+    it("merges custom metadata with platform", async () => {
+      mockSubmitFeedback.mockResolvedValue({ id: "feedback_123" });
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        await result.current.submitFeedback({
+          message: "Test",
+          category: "other" as FeedbackCategory,
+          metadata: { app_version: "1.2.3", screen: "settings" },
+        });
+      });
+
+      expect(mockSubmitFeedback).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: {
+            platform: "ios",
+            app_version: "1.2.3",
+            screen: "settings",
+          },
+        })
+      );
+    });
+  });
+
+  describe("loading state", () => {
+    it("sets isSubmitting true during submission", async () => {
+      let resolveSubmit: (value: unknown) => void;
+      const submitPromise = new Promise((resolve) => {
+        resolveSubmit = resolve;
+      });
+      mockSubmitFeedback.mockReturnValue(submitPromise);
+
+      const { result } = renderHook(() => useFeedback());
+
+      expect(result.current.isSubmitting).toBe(false);
+
+      let submitPromiseResult: Promise<unknown>;
+      act(() => {
+        submitPromiseResult = result.current.submitFeedback({
+          message: "Test",
+          category: "idea" as FeedbackCategory,
+        });
+      });
+
+      await waitFor(() => {
+        expect(result.current.isSubmitting).toBe(true);
+      });
+
+      await act(async () => {
+        resolveSubmit!({ id: "feedback_123" });
+        await submitPromiseResult;
+      });
+
+      expect(result.current.isSubmitting).toBe(false);
+    });
+
+    it("sets isSubmitting false after error", async () => {
+      mockSubmitFeedback.mockRejectedValue(
+        new HarkenApiError(400, { error: { code: "validation_error", message: "Invalid" } })
+      );
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        try {
+          await result.current.submitFeedback({
+            message: "Test",
+            category: "idea" as FeedbackCategory,
+          });
+        } catch {
+          // Expected
+        }
+      });
+
+      expect(result.current.isSubmitting).toBe(false);
+    });
+  });
+
+  describe("error handling", () => {
+    it("sets error state on API failure", async () => {
+      const apiError = new HarkenApiError(400, {
+        error: { code: "validation_error", message: "Message is required" },
+      });
+      mockSubmitFeedback.mockRejectedValue(apiError);
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        try {
+          await result.current.submitFeedback({
+            message: "",
+            category: "idea" as FeedbackCategory,
+          });
+        } catch {
+          // Expected
+        }
+      });
+
+      expect(result.current.error).toBe(apiError);
+    });
+
+    it("sets error state on network failure", async () => {
+      const networkError = new HarkenNetworkError("Network request failed");
+      mockSubmitFeedback.mockRejectedValue(networkError);
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        try {
+          await result.current.submitFeedback({
+            message: "Test",
+            category: "idea" as FeedbackCategory,
+          });
+        } catch {
+          // Expected
+        }
+      });
+
+      expect(result.current.error).toBe(networkError);
+    });
+
+    it("wraps unknown errors in HarkenNetworkError", async () => {
+      mockSubmitFeedback.mockRejectedValue(new Error("Something went wrong"));
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        try {
+          await result.current.submitFeedback({
+            message: "Test",
+            category: "idea" as FeedbackCategory,
+          });
+        } catch {
+          // Expected
+        }
+      });
+
+      expect(result.current.error).toBeInstanceOf(HarkenNetworkError);
+      expect(result.current.error?.message).toBe("Something went wrong");
+    });
+
+    it("clears error on successful submission", async () => {
+      // First, cause an error
+      mockSubmitFeedback.mockRejectedValueOnce(
+        new HarkenApiError(500, { error: { code: "server_error", message: "Error" } })
+      );
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        try {
+          await result.current.submitFeedback({
+            message: "Test",
+            category: "idea" as FeedbackCategory,
+          });
+        } catch {
+          // Expected
+        }
+      });
+
+      expect(result.current.error).not.toBeNull();
+
+      // Now succeed
+      mockSubmitFeedback.mockResolvedValueOnce({ id: "feedback_123" });
+
+      await act(async () => {
+        await result.current.submitFeedback({
+          message: "Test",
+          category: "idea" as FeedbackCategory,
+        });
+      });
+
+      expect(result.current.error).toBeNull();
+    });
+
+    it("clearError clears the error state", async () => {
+      mockSubmitFeedback.mockRejectedValue(
+        new HarkenApiError(400, { error: { code: "error", message: "Error" } })
+      );
+
+      const { result } = renderHook(() => useFeedback());
+
+      await act(async () => {
+        try {
+          await result.current.submitFeedback({
+            message: "Test",
+            category: "idea" as FeedbackCategory,
+          });
+        } catch {
+          // Expected
+        }
+      });
+
+      expect(result.current.error).not.toBeNull();
+
+      act(() => {
+        result.current.clearError();
+      });
+
+      expect(result.current.error).toBeNull();
+    });
+  });
+
+  describe("successful submission", () => {
+    it("returns response from client", async () => {
+      const expectedResponse = { id: "feedback_123", status: "received" };
+      mockSubmitFeedback.mockResolvedValue(expectedResponse);
+
+      const { result } = renderHook(() => useFeedback());
+
+      let response: unknown;
+      await act(async () => {
+        response = await result.current.submitFeedback({
+          message: "Great app!",
+          category: "praise" as FeedbackCategory,
+        });
+      });
+
+      expect(response).toEqual(expectedResponse);
+    });
+  });
+
+  describe("anonymousId requirement", () => {
+    it("throws when anonymousId is not available", async () => {
+      // Override mock to return null anonymousId
+      vi.mocked(useAnonymousId).mockReturnValue({
+        anonymousId: null,
+        isLoading: false,
+      });
+
+      const { result } = renderHook(() => useFeedback());
+
+      await expect(
+        act(async () => {
+          await result.current.submitFeedback({
+            message: "Test",
+            category: "idea" as FeedbackCategory,
+          });
+        })
+      ).rejects.toThrow("Anonymous ID not yet initialized");
+
+      // Restore default mock
+      vi.mocked(useAnonymousId).mockReturnValue({
+        anonymousId: "test-anon-id-123",
+        isLoading: false,
+      });
+    });
+
+    it("exposes isInitializing from useAnonymousId", () => {
+      vi.mocked(useAnonymousId).mockReturnValue({
+        anonymousId: null,
+        isLoading: true,
+      });
+
+      const { result } = renderHook(() => useFeedback());
+
+      expect(result.current.isInitializing).toBe(true);
+
+      // Restore default mock
+      vi.mocked(useAnonymousId).mockReturnValue({
+        anonymousId: "test-anon-id-123",
+        isLoading: false,
+      });
+    });
+  });
+});

package/src/hooks/useFeedback.ts

@@ -1,13 +1,13 @@
-import { useState, useCallback, useMemo } from 'react';
-import { Platform } from 'react-native';
-import type { components } from '../types/index.js';
-import { useHarkenContext } from './useHarkenContext';
-import { useAnonymousId } from './useAnonymousId';
-import { HarkenClient } from '../api/client';
-import { HarkenApiError, HarkenNetworkError } from '../api/errors';
-import type { FeedbackCategory, DeviceMetadata } from '../types';
+import { useState, useCallback, useMemo } from "react";
+import { Platform } from "react-native";
+import type { components } from "../types/index.js";
+import { useHarkenContext } from "./useHarkenContext";
+import { useAnonymousId } from "./useAnonymousId";
+import { HarkenClient } from "../api/client";
+import { HarkenApiError, HarkenNetworkError } from "../api/errors";
+import type { FeedbackCategory, DeviceMetadata } from "../types";
 
-type FeedbackSubmissionResponse = components['schemas']['FeedbackSubmissionResponse'];
+type FeedbackSubmissionResponse = components["schemas"]["FeedbackSubmissionResponse"];
 
 export interface SubmitFeedbackParams {
   /** Feedback message content */
@@ -82,7 +82,7 @@ export function useFeedback(): UseFeedbackResult {
   const submitFeedback = useCallback(
     async (params: SubmitFeedbackParams): Promise<FeedbackSubmissionResponse> => {
       if (!anonymousId) {
-        throw new Error('Anonymous ID not yet initialized. Wait for isInitializing to be false.');
+        throw new Error("Anonymous ID not yet initialized. Wait for isInitializing to be false.");
       }
 
       setIsSubmitting(true);
@@ -93,9 +93,7 @@ export function useFeedback(): UseFeedbackResult {
         // Only set platform if it's a known value (ios, android)
         // Other platforms (web, windows, macos) should be passed via metadata
         const detectedPlatform =
-          Platform.OS === 'ios' ? 'ios' :
-          Platform.OS === 'android' ? 'android' :
-          undefined;
+          Platform.OS === "ios" ? "ios" : Platform.OS === "android" ? "android" : undefined;
 
         const deviceMetadata: DeviceMetadata = {
           ...(detectedPlatform && { platform: detectedPlatform }),
@@ -117,7 +115,7 @@ export function useFeedback(): UseFeedbackResult {
           e instanceof HarkenApiError || e instanceof HarkenNetworkError
             ? e
             : new HarkenNetworkError(
-                e instanceof Error ? e.message : 'Unknown error',
+                e instanceof Error ? e.message : "Unknown error",
                 e instanceof Error ? e : undefined
               );
         setError(harkenError);

package/src/hooks/useHarkenContext.ts

@@ -1,6 +1,6 @@
-import { useContext } from 'react';
-import { HarkenContext } from '../context';
-import type { HarkenContextValue } from '../context';
+import { useContext } from "react";
+import { HarkenContext } from "../context";
+import type { HarkenContextValue } from "../context";
 
 /**
  * Hook to access the full Harken context.
@@ -28,7 +28,7 @@ export function useHarkenContext(): HarkenContextValue {
   const context = useContext(HarkenContext);
 
   if (!context) {
-    throw new Error('useHarkenContext must be used within a HarkenProvider');
+    throw new Error("useHarkenContext must be used within a HarkenProvider");
   }
 
   return context;

package/src/hooks/useHarkenTheme.ts

@@ -1,13 +1,18 @@
-import { useContext } from 'react';
-import { HarkenContext } from '../context';
-import type { HarkenTheme } from '../theme';
+import { useContext } from "react";
+import { HarkenContext } from "../context";
+import type { ResolvedHarkenTheme } from "../theme";
 
 /**
  * Hook to access the current Harken theme.
  *
  * Must be used within a HarkenProvider.
  *
- * @returns The resolved HarkenTheme object
+ * Returns a fully-resolved theme with all component tokens populated.
+ * You can access tokens in two ways:
+ * - Flat: `theme.colors.chipBackground`
+ * - Structured: `theme.components.chip.background`
+ *
+ * @returns The resolved theme object with all fallbacks applied
  * @throws Error if used outside of HarkenProvider
  *
  * @example
@@ -24,12 +29,31 @@ import type { HarkenTheme } from '../theme';
  *   );
  * }
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Using structured component tokens
+ * function ChipComponent() {
+ *   const theme = useHarkenTheme();
+ *   const { chip } = theme.components;
+ *
+ *   return (
+ *     <View style={{
+ *       backgroundColor: chip.background,
+ *       borderRadius: chip.radius,
+ *       padding: chip.paddingVertical,
+ *     }}>
+ *       <Text style={{ color: chip.text }}>Label</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
  */
-export function useHarkenTheme(): HarkenTheme {
+export function useHarkenTheme(): ResolvedHarkenTheme {
   const context = useContext(HarkenContext);
 
   if (!context) {
-    throw new Error('useHarkenTheme must be used within a HarkenProvider');
+    throw new Error("useHarkenTheme must be used within a HarkenProvider");
   }
 
   return context.theme;