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

package/src/hooks/useAttachmentStatus.ts

@@ -0,0 +1,86 @@
+/**
+ * Hook for subscribing to a single attachment's upload status.
+ *
+ * Useful for components that display a single attachment with progress indicator.
+ */
+
+import { useState, useEffect } from 'react';
+import { uploadQueueService } from '../services';
+import { UploadPhase, UploadProgress } from '../domain';
+
+/**
+ * Status information for a single attachment.
+ */
+export interface AttachmentStatus {
+  /** Current upload phase */
+  phase: UploadPhase;
+  /** Upload progress (0.0 - 1.0) */
+  progress: number;
+  /** Error message if failed */
+  error?: string;
+}
+
+/**
+ * Hook to subscribe to a single attachment's upload status.
+ *
+ * Returns null if the attachment is not found in the queue.
+ *
+ * @param attachmentId - Server-assigned attachment ID
+ * @returns Current status or null if not found
+ *
+ * @example
+ * ```tsx
+ * function AttachmentThumbnail({ attachmentId, uri }: Props) {
+ *   const status = useAttachmentStatus(attachmentId);
+ *
+ *   if (!status) return null;
+ *
+ *   return (
+ *     <View>
+ *       <Image source={{ uri }} />
+ *       {status.phase === 'uploading' && (
+ *         <ProgressBar progress={status.progress} />
+ *       )}
+ *       {status.phase === 'failed' && (
+ *         <Text>Error: {status.error}</Text>
+ *       )}
+ *       {status.phase === 'completed' && (
+ *         <Icon name="checkmark" />
+ *       )}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useAttachmentStatus(
+  attachmentId: string
+): AttachmentStatus | null {
+  const [status, setStatus] = useState<AttachmentStatus | null>(() => {
+    // Initialize with current state from queue
+    const item = uploadQueueService.getItemByAttachmentId(attachmentId);
+    if (!item) return null;
+    return {
+      phase: item.phase,
+      progress: item.progress,
+      error: item.lastError,
+    };
+  });
+
+  useEffect(() => {
+    const unsubscribe = uploadQueueService.onProgress(
+      (progress: UploadProgress) => {
+        if (progress.attachmentId !== attachmentId) return;
+
+        setStatus({
+          phase: progress.phase,
+          progress: progress.progress,
+          error: progress.error,
+        });
+      }
+    );
+
+    return unsubscribe;
+  }, [attachmentId]);
+
+  return status;
+}

package/src/hooks/useAttachmentUpload.ts

@@ -0,0 +1,370 @@
+/**
+ * Hook for managing attachment uploads.
+ *
+ * Provides methods for picking images/documents and tracking upload progress.
+ * 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';
+
+/**
+ * State for a single attachment.
+ */
+export interface AttachmentState {
+  /** Server-assigned attachment ID */
+  attachmentId: string;
+  /** Local file URI for preview */
+  localUri: string;
+  /** Original filename */
+  fileName: string;
+  /** MIME type */
+  mimeType: string;
+  /** Current upload phase */
+  phase: UploadPhase;
+  /** Upload progress (0.0 - 1.0) */
+  progress: number;
+  /** Error message if failed */
+  error?: string;
+}
+
+/**
+ * Return type for useAttachmentUpload hook.
+ */
+export interface UseAttachmentUploadResult {
+  /** All current attachments */
+  attachments: AttachmentState[];
+
+  /** Pick image from camera or library */
+  pickImage: (source: 'camera' | 'library') => Promise<AttachmentState | null>;
+
+  /** Pick document (images or PDFs) */
+  pickDocument: () => Promise<AttachmentState | null>;
+
+  /** Add attachment from existing local URI */
+  addAttachment: (params: {
+    uri: string;
+    mimeType: string;
+    fileName: string;
+    fileSize: number;
+  }) => Promise<AttachmentState>;
+
+  /** Retry a failed upload */
+  retryAttachment: (attachmentId: string) => Promise<void>;
+
+  /** Remove attachment (cancels if uploading) */
+  removeAttachment: (attachmentId: string) => Promise<void>;
+
+  /** Get all attachment IDs for feedback submission */
+  getAttachmentIds: () => string[];
+
+  /** True if any uploads are in progress */
+  hasActiveUploads: boolean;
+
+  /** Clear all completed attachments */
+  clearCompleted: () => void;
+
+  /** Clear all failed attachments */
+  clearFailed: () => void;
+}
+
+/**
+ * Hook for managing attachment uploads with background support.
+ *
+ * @example
+ * ```tsx
+ * function FeedbackForm() {
+ *   const {
+ *     attachments,
+ *     pickImage,
+ *     removeAttachment,
+ *     getAttachmentIds,
+ *     hasActiveUploads,
+ *   } = useAttachmentUpload();
+ *
+ *   const handleAddPhoto = async () => {
+ *     await pickImage('library');
+ *   };
+ *
+ *   const handleSubmit = async () => {
+ *     // Can submit even if uploads are still in progress!
+ *     await submitFeedback({
+ *       message: 'Bug report',
+ *       attachmentIds: getAttachmentIds(),
+ *     });
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       {attachments.map(att => (
+ *         <AttachmentPreview
+ *           key={att.attachmentId}
+ *           uri={att.localUri}
+ *           progress={att.progress}
+ *           phase={att.phase}
+ *         />
+ *       ))}
+ *       <Button onPress={handleAddPhoto} title="Add Photo" />
+ *       <Button onPress={handleSubmit} title="Submit" />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useAttachmentUpload(): UseAttachmentUploadResult {
+  const { client, config } = useHarkenContext();
+  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());
+
+  // Initialize upload queue service on first use
+  useEffect(() => {
+    if (!uploadQueueService.initialized) {
+      void uploadQueueService.initialize({
+        client,
+        debug: config.debug,
+      });
+    }
+  }, [client, config.debug]);
+
+  // Subscribe to progress updates from the queue service
+  useEffect(() => {
+    // Guard against service not being initialized
+    if (!uploadQueueService) {
+      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;
+        });
+      }
+    );
+
+    return () => {
+      unsubProgress();
+    };
+  }, []);
+
+  /**
+   * Add an attachment from a local URI.
+   */
+  const addAttachment = useCallback(
+    async (params: {
+      uri: string;
+      mimeType: string;
+      fileName: string;
+      fileSize: number;
+    }): Promise<AttachmentState> => {
+      const { attachmentId } = await uploadQueueService.enqueue({
+        localUri: params.uri,
+        mimeType: params.mimeType,
+        fileName: params.fileName,
+        fileSize: params.fileSize,
+      });
+
+      const state: AttachmentState = {
+        attachmentId,
+        localUri: params.uri,
+        fileName: params.fileName,
+        mimeType: params.mimeType,
+        phase: UploadPhase.QUEUED,
+        progress: 0,
+      };
+
+      attachmentIdsRef.current.add(attachmentId);
+      setAttachments((prev) => new Map(prev).set(attachmentId, state));
+
+      return state;
+    },
+    []
+  );
+
+  /**
+   * Pick an image from camera or photo library.
+   */
+  const pickImage = useCallback(
+    async (source: 'camera' | 'library'): Promise<AttachmentState | null> => {
+      const options: ImagePicker.ImagePickerOptions = {
+        mediaTypes: ['images'],
+        quality: 0.8,
+      };
+
+      const result =
+        source === 'camera'
+          ? await ImagePicker.launchCameraAsync(options)
+          : await ImagePicker.launchImageLibraryAsync(options);
+
+      if (result.canceled || !result.assets[0]) {
+        return null;
+      }
+
+      const asset = result.assets[0];
+      const fileName = asset.fileName ?? `image_${Date.now()}.jpg`;
+      const mimeType = asset.mimeType ?? 'image/jpeg';
+
+      // Get file size - use asset.fileSize if available, otherwise query filesystem
+      let fileSize = asset.fileSize;
+      if (fileSize === undefined || fileSize === null) {
+        const fileInfo = await FileSystem.getInfoAsync(asset.uri);
+        fileSize = fileInfo.exists && fileInfo.size ? fileInfo.size : 0;
+      }
+
+      return addAttachment({
+        uri: asset.uri,
+        mimeType,
+        fileName,
+        fileSize,
+      });
+    },
+    [addAttachment]
+  );
+
+  /**
+   * Pick a document (images or PDFs).
+   */
+  const pickDocument = useCallback(async (): Promise<AttachmentState | null> => {
+    const result = await DocumentPicker.getDocumentAsync({
+      type: ['image/*', 'application/pdf'],
+      copyToCacheDirectory: true,
+    });
+
+    if (result.canceled || !result.assets[0]) {
+      return null;
+    }
+
+    const asset = result.assets[0];
+
+    // Get file size - use asset.size if available, otherwise query filesystem
+    let fileSize = asset.size;
+    if (fileSize === undefined || fileSize === null) {
+      const fileInfo = await FileSystem.getInfoAsync(asset.uri);
+      fileSize = fileInfo.exists && fileInfo.size ? fileInfo.size : 0;
+    }
+
+    return addAttachment({
+      uri: asset.uri,
+      mimeType: asset.mimeType ?? 'application/octet-stream',
+      fileName: asset.name,
+      fileSize,
+    });
+  }, [addAttachment]);
+
+  /**
+   * Retry a failed attachment upload.
+   */
+  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;
+      });
+    },
+    []
+  );
+
+  /**
+   * Get all attachment IDs for feedback submission.
+   */
+  const getAttachmentIds = useCallback((): string[] => {
+    return Array.from(attachments.values()).map((a) => a.attachmentId);
+  }, [attachments]);
+
+  /**
+   * Clear all completed attachments from both local state and queue service.
+   */
+  const clearCompleted = useCallback((): void => {
+    // Clear from queue service (persisted storage)
+    void uploadQueueService.clearCompleted();
+
+    // Clear from local state
+    setAttachments((prev) => {
+      const next = new Map<string, AttachmentState>();
+      for (const [id, att] of prev) {
+        if (att.phase !== UploadPhase.COMPLETED) {
+          next.set(id, att);
+        } else {
+          attachmentIdsRef.current.delete(id);
+        }
+      }
+      return next;
+    });
+  }, []);
+
+  /**
+   * Clear all failed attachments from both local state and queue service.
+   */
+  const clearFailed = useCallback((): void => {
+    // Clear from queue service (persisted storage)
+    void uploadQueueService.clearFailed();
+
+    // Clear from local state
+    setAttachments((prev) => {
+      const next = new Map<string, AttachmentState>();
+      for (const [id, att] of prev) {
+        if (att.phase !== UploadPhase.FAILED) {
+          next.set(id, att);
+        } else {
+          attachmentIdsRef.current.delete(id);
+        }
+      }
+      return next;
+    });
+  }, []);
+
+  // Compute whether any uploads are in progress
+  const hasActiveUploads = Array.from(attachments.values()).some(
+    (a) =>
+      a.phase === UploadPhase.QUEUED ||
+      a.phase === UploadPhase.UPLOADING ||
+      a.phase === UploadPhase.CONFIRMING
+  );
+
+  return {
+    attachments: Array.from(attachments.values()),
+    pickImage,
+    pickDocument,
+    addAttachment,
+    retryAttachment,
+    removeAttachment,
+    getAttachmentIds,
+    hasActiveUploads,
+    clearCompleted,
+    clearFailed,
+  };
+}

package/src/hooks/useFeedback.ts

@@ -0,0 +1,139 @@
+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'];
+
+export interface SubmitFeedbackParams {
+  /** Feedback message content */
+  message: string;
+  /** Feedback category */
+  category: FeedbackCategory;
+  /** Optional title/subject */
+  title?: string;
+  /** Additional device metadata (merged with auto-collected metadata) */
+  metadata?: Partial<DeviceMetadata>;
+  /** Attachment IDs from presigned uploads */
+  attachments?: string[];
+}
+
+export interface UseFeedbackResult {
+  /** Submit feedback to Harken */
+  submitFeedback: (params: SubmitFeedbackParams) => Promise<FeedbackSubmissionResponse>;
+  /** True while a submission is in progress */
+  isSubmitting: boolean;
+  /** Last error from submission attempt */
+  error: HarkenApiError | HarkenNetworkError | null;
+  /** Clear the error state */
+  clearError: () => void;
+  /** True if anonymous ID is still loading */
+  isInitializing: boolean;
+}
+
+/**
+ * Hook for submitting feedback through the Harken API.
+ *
+ * Automatically includes the anonymous ID and device metadata.
+ *
+ * @example
+ * ```tsx
+ * function FeedbackScreen() {
+ *   const { submitFeedback, isSubmitting, error } = useFeedback();
+ *
+ *   const handleSubmit = async () => {
+ *     try {
+ *       await submitFeedback({
+ *         message: 'Great app!',
+ *         category: 'idea',
+ *       });
+ *       // Success!
+ *     } catch (e) {
+ *       // Error is also available in `error` state
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export function useFeedback(): UseFeedbackResult {
+  const { config } = useHarkenContext();
+  const { anonymousId, isLoading: isInitializing } = useAnonymousId();
+
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<HarkenApiError | HarkenNetworkError | null>(null);
+
+  // Create client instance (memoized)
+  const client = useMemo(() => {
+    return new HarkenClient({
+      publishableKey: config.publishableKey,
+      userToken: config.userToken,
+      baseUrl: config.apiBaseUrl,
+    });
+  }, [config.publishableKey, config.userToken, config.apiBaseUrl]);
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  const submitFeedback = useCallback(
+    async (params: SubmitFeedbackParams): Promise<FeedbackSubmissionResponse> => {
+      if (!anonymousId) {
+        throw new Error('Anonymous ID not yet initialized. Wait for isInitializing to be false.');
+      }
+
+      setIsSubmitting(true);
+      setError(null);
+
+      try {
+        // Collect device metadata
+        // 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;
+
+        const deviceMetadata: DeviceMetadata = {
+          ...(detectedPlatform && { platform: detectedPlatform }),
+          ...params.metadata,
+        };
+
+        const response = await client.submitFeedback({
+          message: params.message,
+          category: params.category,
+          title: params.title,
+          anon_id: anonymousId,
+          metadata: deviceMetadata,
+          attachments: params.attachments,
+        });
+
+        return response;
+      } catch (e) {
+        const harkenError =
+          e instanceof HarkenApiError || e instanceof HarkenNetworkError
+            ? e
+            : new HarkenNetworkError(
+                e instanceof Error ? e.message : 'Unknown error',
+                e instanceof Error ? e : undefined
+              );
+        setError(harkenError);
+        throw harkenError;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [anonymousId, client]
+  );
+
+  return {
+    submitFeedback,
+    isSubmitting,
+    error,
+    clearError,
+    isInitializing,
+  };
+}

package/src/hooks/useHarkenContext.ts

@@ -0,0 +1,35 @@
+import { useContext } from 'react';
+import { HarkenContext } from '../context';
+import type { HarkenContextValue } from '../context';
+
+/**
+ * Hook to access the full Harken context.
+ *
+ * Provides access to theme, config, and SDK state.
+ * Must be used within a HarkenProvider.
+ *
+ * @returns The full HarkenContextValue
+ * @throws Error if used outside of HarkenProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { theme, isDarkMode, config } = useHarkenContext();
+ *
+ *   return (
+ *     <View>
+ *       <Text>Dark mode: {isDarkMode ? 'on' : 'off'}</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useHarkenContext(): HarkenContextValue {
+  const context = useContext(HarkenContext);
+
+  if (!context) {
+    throw new Error('useHarkenContext must be used within a HarkenProvider');
+  }
+
+  return context;
+}

package/src/hooks/useHarkenTheme.ts

@@ -0,0 +1,36 @@
+import { useContext } from 'react';
+import { HarkenContext } from '../context';
+import type { HarkenTheme } from '../theme';
+
+/**
+ * Hook to access the current Harken theme.
+ *
+ * Must be used within a HarkenProvider.
+ *
+ * @returns The resolved HarkenTheme object
+ * @throws Error if used outside of HarkenProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const theme = useHarkenTheme();
+ *
+ *   return (
+ *     <View style={{ backgroundColor: theme.colors.background }}>
+ *       <Text style={{ color: theme.colors.text }}>
+ *         Hello
+ *       </Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useHarkenTheme(): HarkenTheme {
+  const context = useContext(HarkenContext);
+
+  if (!context) {
+    throw new Error('useHarkenTheme must be used within a HarkenProvider');
+  }
+
+  return context.theme;
+}