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

package/src/components/index.ts

@@ -0,0 +1,39 @@
+// Base themed components
+export { ThemedText } from './ThemedText';
+export type { ThemedTextProps, TextVariant } from './ThemedText';
+
+export { ThemedTextInput } from './ThemedTextInput';
+export type { ThemedTextInputProps } from './ThemedTextInput';
+
+export { ThemedButton } from './ThemedButton';
+export type { ThemedButtonProps, ButtonVariant } from './ThemedButton';
+
+// Feedback components
+export { CategorySelector, DEFAULT_CATEGORIES } from './CategorySelector';
+export type { CategorySelectorProps, CategoryOption } from './CategorySelector';
+
+export { FeedbackForm } from './FeedbackForm';
+export type { FeedbackFormProps, FeedbackFormData } from './FeedbackForm';
+
+// Note: FeedbackSheet is exported from the main entry point (comes from attachments module)
+// to provide full attachment support by default.
+
+// Attachment components
+export { AttachmentPicker } from './AttachmentPicker';
+export type {
+  AttachmentPickerProps,
+  AttachmentSource,
+  PickerOptionConfig,
+} from './AttachmentPicker';
+
+export { UploadStatusOverlay } from './UploadStatusOverlay';
+export type {
+  UploadStatusOverlayProps,
+  UploadStatusLabels,
+} from './UploadStatusOverlay';
+
+export { AttachmentPreview } from './AttachmentPreview';
+export type { AttachmentPreviewProps } from './AttachmentPreview';
+
+export { AttachmentGrid } from './AttachmentGrid';
+export type { AttachmentGridProps } from './AttachmentGrid';

package/src/context/HarkenContext.tsx

@@ -0,0 +1,129 @@
+import React, { createContext, useMemo } from 'react';
+import { useColorScheme } from 'react-native';
+import type { HarkenTheme, ThemeMode } from '../theme';
+import { lightTheme, darkTheme, createTheme } from '../theme';
+import type { HarkenConfig, HarkenProviderProps } from '../types';
+import { IdentityStore, createDefaultStorage } from '../storage';
+import { HarkenClient } from '../api/client';
+
+/**
+ * Context value provided by HarkenProvider.
+ */
+export interface HarkenContextValue {
+  /** The resolved theme based on mode and overrides */
+  theme: HarkenTheme;
+  /** Current theme mode */
+  themeMode: ThemeMode;
+  /** Whether dark mode is currently active */
+  isDarkMode: boolean;
+  /** SDK configuration */
+  config: HarkenConfig;
+  /** Identity store for anonymous ID management */
+  identityStore: IdentityStore;
+  /** API client instance */
+  client: HarkenClient;
+}
+
+/**
+ * React context for Harken SDK state.
+ * @internal
+ */
+export const HarkenContext = createContext<HarkenContextValue | null>(null);
+
+/**
+ * Provider component that configures the Harken SDK.
+ *
+ * Wrap your app with this provider to enable Harken feedback components.
+ * By default, uses expo-secure-store for persistent anonymous ID storage
+ * (falls back to in-memory storage if not available).
+ *
+ * @example
+ * ```tsx
+ * import { HarkenProvider, FeedbackSheet } from '@harkenapp/sdk-react-native';
+ *
+ * function App() {
+ *   return (
+ *     <HarkenProvider config={{ publishableKey: 'pk_live_xxxx' }}>
+ *       <FeedbackSheet />
+ *     </HarkenProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom storage implementation
+ * import { HarkenProvider, createSecureStoreAdapter } from '@harkenapp/sdk-react-native';
+ * import * as SecureStore from 'expo-secure-store';
+ *
+ * const storage = createSecureStoreAdapter(SecureStore);
+ *
+ * <HarkenProvider config={{ publishableKey: 'pk_live_xxxx' }} storage={storage}>
+ *   <YourApp />
+ * </HarkenProvider>
+ * ```
+ */
+export function HarkenProvider({
+  config,
+  themeMode = 'system',
+  lightTheme: lightOverrides,
+  darkTheme: darkOverrides,
+  storage,
+  children,
+}: HarkenProviderProps): React.JSX.Element {
+  // Get system color scheme
+  const systemColorScheme = useColorScheme();
+
+  // Determine if dark mode should be active
+  const isDarkMode = useMemo(() => {
+    if (themeMode === 'dark') return true;
+    if (themeMode === 'light') return false;
+    // 'system' mode - follow device preference
+    return systemColorScheme === 'dark';
+  }, [themeMode, systemColorScheme]);
+
+  // Build the resolved theme
+  const theme = useMemo(() => {
+    const baseTheme = isDarkMode ? darkTheme : lightTheme;
+    const overrides = isDarkMode ? darkOverrides : lightOverrides;
+    return createTheme(baseTheme, overrides);
+  }, [isDarkMode, lightOverrides, darkOverrides]);
+
+  // Create identity store (memoized to persist across re-renders)
+  // Uses expo-secure-store by default if available, otherwise falls back to memory
+  const identityStore = useMemo(() => {
+    const storageImpl = storage ?? createDefaultStorage();
+    return new IdentityStore(storageImpl);
+  }, [storage]);
+
+  // Create API client (memoized)
+  const client = useMemo(() => {
+    return new HarkenClient({
+      publishableKey: config.publishableKey,
+      userToken: config.userToken,
+      baseUrl: config.apiBaseUrl,
+    });
+  }, [config.publishableKey, config.userToken, config.apiBaseUrl]);
+
+  // Note: Upload queue service initialization has been moved to the attachments module.
+  // When using attachments, the service is initialized when useAttachmentUpload is first called.
+
+  // Memoize the context value
+  const contextValue = useMemo<HarkenContextValue>(
+    () => ({
+      theme,
+      themeMode,
+      isDarkMode,
+      config,
+      identityStore,
+      client,
+    }),
+    [theme, themeMode, isDarkMode, config, identityStore, client]
+  );
+
+  return (
+    <HarkenContext.Provider value={contextValue}>
+      {children}
+    </HarkenContext.Provider>
+  );
+}

package/src/context/index.ts

@@ -0,0 +1,2 @@
+export { HarkenProvider, HarkenContext } from './HarkenContext';
+export type { HarkenContextValue } from './HarkenContext';

package/src/domain/index.ts

@@ -0,0 +1,12 @@
+export {
+  UploadPhase,
+  DEFAULT_UPLOAD_RETRY_CONFIG,
+} from './upload-queue';
+
+export type {
+  QueueItem,
+  QueueStatus,
+  UploadProgress,
+  PersistedQueue,
+  UploadRetryConfig,
+} from './upload-queue';

package/src/domain/upload-queue.ts

@@ -0,0 +1,131 @@
+/**
+ * Upload queue domain types.
+ *
+ * These types define the state machine for background attachment uploads.
+ */
+
+/**
+ * Phases of the upload lifecycle.
+ */
+export enum UploadPhase {
+  /** Waiting in queue to be processed */
+  QUEUED = 'queued',
+  /** Currently uploading to storage */
+  UPLOADING = 'uploading',
+  /** Upload complete, confirming with server */
+  CONFIRMING = 'confirming',
+  /** Successfully uploaded and confirmed */
+  COMPLETED = 'completed',
+  /** Failed after max retries */
+  FAILED = 'failed',
+}
+
+/**
+ * A single item in the upload queue.
+ */
+export interface QueueItem {
+  /** Internal queue item ID */
+  id: string;
+  /** Server-assigned attachment ID */
+  attachmentId: string;
+  /** Local file URI (file://) */
+  localUri: string;
+  /** Presigned upload URL */
+  uploadUrl: string;
+  /** ISO timestamp when upload URL expires */
+  uploadExpiresAt: string;
+  /** MIME type (e.g., 'image/png') */
+  mimeType: string;
+  /** Original filename */
+  fileName: string;
+  /** File size in bytes */
+  fileSize: number;
+
+  // State
+  /** Current phase in upload lifecycle */
+  phase: UploadPhase;
+  /** Upload progress (0.0 - 1.0) */
+  progress: number;
+  /** Current attempt number (1-based) */
+  attemptNumber: number;
+  /** Maximum retry attempts */
+  maxAttempts: number;
+  /** Last error message if failed */
+  lastError?: string;
+
+  // Timestamps
+  /** ISO timestamp when item was queued */
+  createdAt: string;
+  /** ISO timestamp when upload started */
+  startedAt?: string;
+  /** ISO timestamp when completed or failed */
+  completedAt?: string;
+  /** ISO timestamp for scheduled retry (backoff) */
+  scheduledRetryAt?: string;
+}
+
+/**
+ * Summary of queue state.
+ */
+export interface QueueStatus {
+  /** Total items in queue */
+  total: number;
+  /** Items waiting to be processed */
+  queued: number;
+  /** Items currently uploading or confirming */
+  uploading: number;
+  /** Successfully completed items */
+  completed: number;
+  /** Failed items (max retries exceeded) */
+  failed: number;
+  /** Whether queue is paused (e.g., offline) */
+  isPaused: boolean;
+}
+
+/**
+ * Progress update for a single attachment.
+ */
+export interface UploadProgress {
+  /** Server-assigned attachment ID */
+  attachmentId: string;
+  /** Current phase */
+  phase: UploadPhase;
+  /** Upload progress (0.0 - 1.0) */
+  progress: number;
+  /** Error message if failed */
+  error?: string;
+}
+
+/**
+ * Persisted queue schema for AsyncStorage.
+ */
+export interface PersistedQueue {
+  /** Schema version for migrations */
+  version: number;
+  /** Queue items */
+  items: QueueItem[];
+}
+
+/**
+ * Configuration for upload retry behavior.
+ */
+export interface UploadRetryConfig {
+  /** Base delay in milliseconds (default: 2000) */
+  baseDelayMs: number;
+  /** Maximum delay in milliseconds (default: 60000) */
+  maxDelayMs: number;
+  /** Maximum number of attempts (default: 3) */
+  maxAttempts: number;
+  /** Random jitter in milliseconds (default: 1000) */
+  jitterMs: number;
+}
+
+/**
+ * Default retry configuration per feature spec D4.
+ */
+export const DEFAULT_UPLOAD_RETRY_CONFIG: UploadRetryConfig = {
+  baseDelayMs: 2000,
+  maxDelayMs: 60000,
+  maxAttempts: 3,
+  jitterMs: 1000,
+};

package/src/hooks/index.ts

@@ -0,0 +1,10 @@
+// Core hooks (no native module dependencies)
+export { useHarkenTheme } from './useHarkenTheme';
+export { useHarkenContext } from './useHarkenContext';
+export { useAnonymousId } from './useAnonymousId';
+export { useFeedback } from './useFeedback';
+export type { SubmitFeedbackParams, UseFeedbackResult } from './useFeedback';
+
+// Note: Attachment hooks (useAttachmentUpload, useAttachmentStatus) are
+// exported from '@harkenapp/sdk-react-native/attachments' to avoid eager
+// loading of native modules (expo-file-system, expo-image-picker, etc.)

package/src/hooks/useAnonymousId.ts

@@ -0,0 +1,68 @@
+import { useState, useEffect, useContext } from 'react';
+import { HarkenContext } from '../context';
+
+/**
+ * Hook to access the anonymous ID for the current installation.
+ *
+ * The anonymous ID is a stable UUID that persists across app sessions.
+ * It's generated once and stored securely on the device.
+ *
+ * @returns Object with the anonymous ID and loading state
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { anonymousId, isLoading } = useAnonymousId();
+ *
+ *   if (isLoading) {
+ *     return <Text>Loading...</Text>;
+ *   }
+ *
+ *   return <Text>ID: {anonymousId}</Text>;
+ * }
+ * ```
+ */
+export function useAnonymousId(): {
+  /** The anonymous ID, or null while loading */
+  anonymousId: string | null;
+  /** True while the ID is being loaded from storage */
+  isLoading: boolean;
+} {
+  const context = useContext(HarkenContext);
+
+  if (!context) {
+    throw new Error('useAnonymousId must be used within a HarkenProvider');
+  }
+
+  // Capture identityStore to satisfy TypeScript narrowing in useEffect
+  const { identityStore } = context;
+
+  const [anonymousId, setAnonymousId] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    let mounted = true;
+
+    async function loadAnonymousId() {
+      try {
+        const id = await identityStore.getAnonymousId();
+        if (mounted) {
+          setAnonymousId(id);
+          setIsLoading(false);
+        }
+      } catch {
+        if (mounted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void loadAnonymousId();
+
+    return () => {
+      mounted = false;
+    };
+  }, [identityStore]);
+
+  return { anonymousId, isLoading };
+}

package/src/hooks/useAttachmentPicker.ts

@@ -0,0 +1,243 @@
+/**
+ * Hook for managing the attachment picker with smart source selection.
+ *
+ * Provides configurable attachment sources and automatically handles:
+ * - Skipping the picker modal when only one source is enabled
+ * - Warning when no sources are enabled
+ */
+
+import { useState, useCallback, useMemo, useEffect } from 'react';
+import { useAttachmentUpload } from './useAttachmentUpload';
+import type { UseAttachmentUploadResult } from './useAttachmentUpload';
+import type { AttachmentPickerProps } from '../components/AttachmentPicker';
+
+/**
+ * Configuration for which attachment sources are enabled.
+ */
+export interface AttachmentSourceConfig {
+  /** Enable camera source. @default true */
+  camera?: boolean;
+  /** Enable photo library source. @default true */
+  library?: boolean;
+  /** Enable file/document picker source. @default true */
+  files?: boolean;
+}
+
+/**
+ * Return type for useAttachmentPicker hook.
+ */
+export interface UseAttachmentPickerResult extends UseAttachmentUploadResult {
+  /** Open the attachment picker (or directly invoke source if only one enabled) */
+  openPicker: () => void;
+
+  /** Whether the picker modal is visible */
+  isPickerVisible: boolean;
+
+  /** Close the picker modal */
+  closePicker: () => void;
+
+  /** Props to spread onto AttachmentPicker component */
+  pickerProps: Pick<
+    AttachmentPickerProps,
+    'visible' | 'onClose' | 'onTakePhoto' | 'onPickFromLibrary' | 'onPickDocument' | 'options'
+  >;
+
+  /** Which sources are enabled */
+  enabledSources: {
+    camera: boolean;
+    library: boolean;
+    files: boolean;
+  };
+
+  /** Count of enabled sources */
+  enabledSourceCount: number;
+}
+
+/**
+ * Hook for managing the attachment picker with smart source selection.
+ *
+ * When only one source is enabled, calling `openPicker()` will skip the modal
+ * and directly open that source. When no sources are enabled, a warning is logged.
+ *
+ * @example
+ * ```tsx
+ * // Allow only photo library
+ * const { openPicker, pickerProps, attachments } = useAttachmentPicker({
+ *   camera: false,
+ *   library: true,
+ *   files: false,
+ * });
+ *
+ * // openPicker() will directly open photo library without showing modal
+ *
+ * return (
+ *   <>
+ *     <Button onPress={openPicker} title="Add Photo" />
+ *     <AttachmentPicker {...pickerProps} />
+ *   </>
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With FeedbackSheet integration
+ * const {
+ *   openPicker,
+ *   pickerProps,
+ *   attachments,
+ *   removeAttachment,
+ *   retryAttachment,
+ * } = useAttachmentPicker({
+ *   camera: true,
+ *   library: true,
+ *   files: false, // Disable document picker
+ * });
+ * ```
+ */
+export function useAttachmentPicker(
+  sourceConfig: AttachmentSourceConfig = {}
+): UseAttachmentPickerResult {
+  const {
+    camera: cameraEnabled = true,
+    library: libraryEnabled = true,
+    files: filesEnabled = true,
+  } = sourceConfig;
+
+  const [isPickerVisible, setIsPickerVisible] = useState(false);
+
+  const uploadResult = useAttachmentUpload();
+  const { pickImage, pickDocument } = uploadResult;
+
+  // Calculate enabled sources
+  const enabledSources = useMemo(
+    () => ({
+      camera: cameraEnabled,
+      library: libraryEnabled,
+      files: filesEnabled,
+    }),
+    [cameraEnabled, libraryEnabled, filesEnabled]
+  );
+
+  const enabledSourceCount = useMemo(() => {
+    let count = 0;
+    if (cameraEnabled) count++;
+    if (libraryEnabled) count++;
+    if (filesEnabled) count++;
+    return count;
+  }, [cameraEnabled, libraryEnabled, filesEnabled]);
+
+  // Auto-close picker if sources change to 0 or 1 while visible
+  // This prevents the iOS ActionSheet from showing with no/single options
+  useEffect(() => {
+    if (isPickerVisible && enabledSourceCount < 2) {
+      setIsPickerVisible(false);
+    }
+  }, [isPickerVisible, enabledSourceCount]);
+
+  // Handlers for each source
+  const handleTakePhoto = useCallback(async () => {
+    setIsPickerVisible(false);
+    try {
+      await pickImage('camera');
+    } catch (e) {
+      console.error('[Harken] Failed to take photo:', e);
+    }
+  }, [pickImage]);
+
+  const handlePickFromLibrary = useCallback(async () => {
+    setIsPickerVisible(false);
+    try {
+      await pickImage('library');
+    } catch (e) {
+      console.error('[Harken] Failed to pick from library:', e);
+    }
+  }, [pickImage]);
+
+  const handlePickDocument = useCallback(async () => {
+    setIsPickerVisible(false);
+    try {
+      await pickDocument();
+    } catch (e) {
+      console.error('[Harken] Failed to pick document:', e);
+    }
+  }, [pickDocument]);
+
+  const closePicker = useCallback(() => {
+    setIsPickerVisible(false);
+  }, []);
+
+  /**
+   * Smart picker opener:
+   * - 0 sources enabled: log warning, do nothing
+   * - 1 source enabled: directly invoke that source
+   * - 2+ sources enabled: show picker modal
+   */
+  const openPicker = useCallback(() => {
+    if (enabledSourceCount === 0) {
+      console.warn(
+        '[Harken] useAttachmentPicker: No attachment sources are enabled. ' +
+          'Enable at least one of: camera, library, or files.'
+      );
+      return;
+    }
+
+    if (enabledSourceCount === 1) {
+      // Directly invoke the single enabled source
+      if (cameraEnabled) {
+        void handleTakePhoto();
+      } else if (libraryEnabled) {
+        void handlePickFromLibrary();
+      } else if (filesEnabled) {
+        void handlePickDocument();
+      }
+      return;
+    }
+
+    // Multiple sources enabled - show the picker
+    setIsPickerVisible(true);
+  }, [
+    enabledSourceCount,
+    cameraEnabled,
+    libraryEnabled,
+    filesEnabled,
+    handleTakePhoto,
+    handlePickFromLibrary,
+    handlePickDocument,
+  ]);
+
+  // Build picker props with hidden options for disabled sources
+  const pickerProps = useMemo(
+    () => ({
+      visible: isPickerVisible,
+      onClose: closePicker,
+      onTakePhoto: handleTakePhoto,
+      onPickFromLibrary: handlePickFromLibrary,
+      onPickDocument: handlePickDocument,
+      options: {
+        camera: { hidden: !cameraEnabled },
+        library: { hidden: !libraryEnabled },
+        document: { hidden: !filesEnabled },
+      },
+    }),
+    [
+      isPickerVisible,
+      closePicker,
+      handleTakePhoto,
+      handlePickFromLibrary,
+      handlePickDocument,
+      cameraEnabled,
+      libraryEnabled,
+      filesEnabled,
+    ]
+  );
+
+  return {
+    ...uploadResult,
+    openPicker,
+    isPickerVisible,
+    closePicker,
+    pickerProps,
+    enabledSources,
+    enabledSourceCount,
+  };
+}