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

package/src/services/uploadQueueStorage.ts

@@ -0,0 +1,78 @@
+/**
+ * Persistent storage for the upload queue.
+ *
+ * Uses AsyncStorage to persist queue state across app restarts.
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { PersistedQueue, QueueItem } from '../domain';
+
+const STORAGE_KEY = '@harkenapp/upload-queue';
+const CURRENT_VERSION = 1;
+
+/**
+ * Manages persistent storage of the upload queue.
+ */
+export class UploadQueueStorage {
+  /**
+   * Load queue items from persistent storage.
+   * Returns empty array if no queue exists or on error.
+   */
+  async loadQueue(): Promise<QueueItem[]> {
+    try {
+      const raw = await AsyncStorage.getItem(STORAGE_KEY);
+      if (!raw) {
+        return [];
+      }
+
+      const parsed = JSON.parse(raw) as PersistedQueue;
+
+      // Handle version migrations
+      if (parsed.version !== CURRENT_VERSION) {
+        return this.migrateQueue(parsed);
+      }
+
+      return parsed.items;
+    } catch (error) {
+      console.error('[UploadQueueStorage] Failed to load queue:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Save queue items to persistent storage.
+   */
+  async saveQueue(items: QueueItem[]): Promise<void> {
+    try {
+      const data: PersistedQueue = {
+        version: CURRENT_VERSION,
+        items,
+      };
+      await AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+    } catch (error) {
+      console.error('[UploadQueueStorage] Failed to save queue:', error);
+    }
+  }
+
+  /**
+   * Clear all persisted queue data.
+   */
+  async clearQueue(): Promise<void> {
+    try {
+      await AsyncStorage.removeItem(STORAGE_KEY);
+    } catch (error) {
+      console.error('[UploadQueueStorage] Failed to clear queue:', error);
+    }
+  }
+
+  /**
+   * Migrate queue data from older versions.
+   * For now, unknown versions are reset to empty.
+   */
+  private migrateQueue(data: PersistedQueue): QueueItem[] {
+    console.warn(
+      `[UploadQueueStorage] Unknown queue version ${data.version}, resetting`
+    );
+    return [];
+  }
+}

package/src/storage/IdentityStore.ts

@@ -0,0 +1,89 @@
+import type { SecureStorage } from './types';
+import { STORAGE_KEYS } from './types';
+import { generateUUID } from '../utils';
+
+/**
+ * Manages anonymous identity persistence.
+ *
+ * The identity store generates and persists a stable anonymous ID
+ * that uniquely identifies the app installation without collecting PII.
+ */
+export class IdentityStore {
+  private storage: SecureStorage;
+  private cachedAnonId: string | null = null;
+  private initPromise: Promise<string> | null = null;
+
+  constructor(storage: SecureStorage) {
+    this.storage = storage;
+  }
+
+  /**
+   * Get the anonymous ID, creating one if it doesn't exist.
+   *
+   * This method is safe to call multiple times concurrently.
+   * The ID is cached after first retrieval/creation.
+   *
+   * @returns The stable anonymous ID for this installation
+   */
+  async getAnonymousId(): Promise<string> {
+    // Return cached value if available
+    if (this.cachedAnonId) {
+      return this.cachedAnonId;
+    }
+
+    // Ensure only one initialization happens
+    if (!this.initPromise) {
+      this.initPromise = this.initializeAnonymousId();
+    }
+
+    return this.initPromise;
+  }
+
+  /**
+   * Initialize the anonymous ID by loading from storage or generating a new one.
+   */
+  private async initializeAnonymousId(): Promise<string> {
+    try {
+      // Try to load existing ID
+      const existingId = await this.storage.getItem(STORAGE_KEYS.ANON_ID);
+
+      if (existingId && this.isValidUUID(existingId)) {
+        this.cachedAnonId = existingId;
+        return existingId;
+      }
+
+      // Generate and persist a new ID
+      const newId = generateUUID();
+      await this.storage.setItem(STORAGE_KEYS.ANON_ID, newId);
+      this.cachedAnonId = newId;
+      return newId;
+    } catch {
+      // If storage fails, generate a transient ID
+      // This ensures the SDK still works even if storage is unavailable
+      const fallbackId = generateUUID();
+      this.cachedAnonId = fallbackId;
+      return fallbackId;
+    }
+  }
+
+  /**
+   * Clear the stored anonymous ID.
+   *
+   * After calling this, the next call to getAnonymousId will generate a new ID.
+   * Use this for "reset" functionality or testing.
+   */
+  async clearAnonymousId(): Promise<void> {
+    this.cachedAnonId = null;
+    this.initPromise = null;
+    await this.storage.deleteItem(STORAGE_KEYS.ANON_ID);
+  }
+
+  /**
+   * Validate that a string is a valid UUID v4 format.
+   */
+  private isValidUUID(value: string): boolean {
+    const uuidRegex =
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(value);
+  }
+}

package/src/storage/SecureStoreAdapter.ts

@@ -0,0 +1,59 @@
+import type { SecureStorage } from './types';
+
+/**
+ * Adapter for expo-secure-store.
+ *
+ * This adapter wraps expo-secure-store to implement the SecureStorage interface.
+ * It dynamically imports expo-secure-store to avoid bundling issues when not used.
+ *
+ * @example
+ * ```tsx
+ * import { createSecureStoreAdapter } from '@harkenapp/sdk-react-native';
+ * import * as SecureStore from 'expo-secure-store';
+ *
+ * const storage = createSecureStoreAdapter(SecureStore);
+ * ```
+ */
+export function createSecureStoreAdapter(secureStore: {
+  getItemAsync: (key: string) => Promise<string | null>;
+  setItemAsync: (key: string, value: string) => Promise<void>;
+  deleteItemAsync: (key: string) => Promise<void>;
+}): SecureStorage {
+  return {
+    async getItem(key: string): Promise<string | null> {
+      return secureStore.getItemAsync(key);
+    },
+
+    async setItem(key: string, value: string): Promise<void> {
+      await secureStore.setItemAsync(key, value);
+    },
+
+    async deleteItem(key: string): Promise<void> {
+      await secureStore.deleteItemAsync(key);
+    },
+  };
+}
+
+/**
+ * In-memory storage for testing or when secure storage is unavailable.
+ * Values are not persisted across app restarts.
+ *
+ * @internal
+ */
+export function createMemoryStorage(): SecureStorage {
+  const storage = new Map<string, string>();
+
+  return {
+    async getItem(key: string): Promise<string | null> {
+      return storage.get(key) ?? null;
+    },
+
+    async setItem(key: string, value: string): Promise<void> {
+      storage.set(key, value);
+    },
+
+    async deleteItem(key: string): Promise<void> {
+      storage.delete(key);
+    },
+  };
+}

package/src/storage/defaultStorage.ts

@@ -0,0 +1,109 @@
+import type { SecureStorage } from './types';
+import { createMemoryStorage } from './SecureStoreAdapter';
+
+/**
+ * Cached default storage instance.
+ * @internal
+ */
+let defaultStorageInstance: SecureStorage | null = null;
+
+/**
+ * Whether we've already attempted to load expo-secure-store.
+ * @internal
+ */
+let hasAttemptedLoad = false;
+
+/**
+ * Creates or returns the default storage implementation.
+ *
+ * Attempts to use expo-secure-store if available, falling back to
+ * in-memory storage if not installed or if loading fails.
+ *
+ * @internal
+ */
+export async function getDefaultStorage(): Promise<SecureStorage> {
+  if (defaultStorageInstance) {
+    return defaultStorageInstance;
+  }
+
+  if (!hasAttemptedLoad) {
+    hasAttemptedLoad = true;
+
+    try {
+      // Dynamically import expo-secure-store
+      const SecureStore = await import('expo-secure-store');
+
+      defaultStorageInstance = {
+        async getItem(key: string): Promise<string | null> {
+          return SecureStore.getItemAsync(key);
+        },
+        async setItem(key: string, value: string): Promise<void> {
+          await SecureStore.setItemAsync(key, value);
+        },
+        async deleteItem(key: string): Promise<void> {
+          await SecureStore.deleteItemAsync(key);
+        },
+      };
+
+      return defaultStorageInstance;
+    } catch {
+      // expo-secure-store not available, fall back to memory storage
+      console.warn(
+        '[Harken] expo-secure-store not available. Using in-memory storage. ' +
+          'Anonymous IDs will not persist across app restarts. ' +
+          'Install expo-secure-store for persistent storage.'
+      );
+    }
+  }
+
+  // Fall back to memory storage
+  if (!defaultStorageInstance) {
+    defaultStorageInstance = createMemoryStorage();
+  }
+
+  return defaultStorageInstance;
+}
+
+/**
+ * Synchronously creates a storage implementation.
+ *
+ * Returns a lazy wrapper that will resolve to expo-secure-store if available,
+ * or memory storage if not. The actual storage is initialized on first use.
+ *
+ * @internal
+ */
+export function createDefaultStorage(): SecureStorage {
+  // Return a lazy wrapper that initializes on first use
+  let resolvedStorage: SecureStorage | null = null;
+  let initPromise: Promise<SecureStorage> | null = null;
+
+  const ensureInitialized = async (): Promise<SecureStorage> => {
+    if (resolvedStorage) {
+      return resolvedStorage;
+    }
+
+    if (!initPromise) {
+      initPromise = getDefaultStorage().then((storage) => {
+        resolvedStorage = storage;
+        return storage;
+      });
+    }
+
+    return initPromise;
+  };
+
+  return {
+    async getItem(key: string): Promise<string | null> {
+      const storage = await ensureInitialized();
+      return storage.getItem(key);
+    },
+    async setItem(key: string, value: string): Promise<void> {
+      const storage = await ensureInitialized();
+      await storage.setItem(key, value);
+    },
+    async deleteItem(key: string): Promise<void> {
+      const storage = await ensureInitialized();
+      await storage.deleteItem(key);
+    },
+  };
+}

package/src/storage/index.ts

@@ -0,0 +1,5 @@
+export type { SecureStorage } from './types';
+export { STORAGE_KEYS } from './types';
+export { createSecureStoreAdapter, createMemoryStorage } from './SecureStoreAdapter';
+export { createDefaultStorage } from './defaultStorage';
+export { IdentityStore } from './IdentityStore';

package/src/storage/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Interface for secure key-value storage.
+ * Default implementation uses expo-secure-store.
+ * Can be replaced with custom implementations.
+ */
+export interface SecureStorage {
+  /**
+   * Retrieve a value from secure storage.
+   * @param key - The key to retrieve
+   * @returns The stored value, or null if not found
+   */
+  getItem(key: string): Promise<string | null>;
+
+  /**
+   * Store a value in secure storage.
+   * @param key - The key to store under
+   * @param value - The value to store
+   */
+  setItem(key: string, value: string): Promise<void>;
+
+  /**
+   * Remove a value from secure storage.
+   * @param key - The key to remove
+   */
+  deleteItem(key: string): Promise<void>;
+}
+
+/**
+ * Storage keys used by the Harken SDK.
+ * @internal
+ */
+export const STORAGE_KEYS = {
+  ANON_ID: 'harken_anon_id',
+} as const;

package/src/theme/defaults.ts

@@ -0,0 +1,151 @@
+import type {
+  HarkenColors,
+  HarkenTypography,
+  HarkenSpacing,
+  HarkenRadii,
+  HarkenTheme,
+} from './types';
+
+/**
+ * Default light mode colors.
+ * Neutral, accessible palette with no hard-coded branding.
+ */
+export const lightColors: HarkenColors = {
+  primary: '#2563EB', // Blue 600
+  primaryPressed: '#1D4ED8', // Blue 700
+  background: '#FFFFFF',
+  backgroundSecondary: '#F9FAFB', // Gray 50
+  text: '#111827', // Gray 900
+  textSecondary: '#6B7280', // Gray 500
+  textPlaceholder: '#9CA3AF', // Gray 400
+  textOnPrimary: '#FFFFFF',
+  border: '#E5E7EB', // Gray 200
+  borderFocused: '#2563EB', // Blue 600
+  error: '#DC2626', // Red 600
+  success: '#16A34A', // Green 600
+  warning: '#D97706', // Amber 600
+  info: '#2563EB', // Blue 600
+  overlay: 'rgba(0, 0, 0, 0.3)',
+  overlayDark: 'rgba(0, 0, 0, 0.6)',
+  accent1: '#2563EB', // Blue 600 (camera)
+  accent2: '#16A34A', // Green 600 (library)
+  accent3: '#D97706', // Amber 600 (files)
+};
+
+/**
+ * Default dark mode colors.
+ * Inverted palette optimized for dark backgrounds.
+ */
+export const darkColors: HarkenColors = {
+  primary: '#3B82F6', // Blue 500
+  primaryPressed: '#2563EB', // Blue 600
+  background: '#111827', // Gray 900
+  backgroundSecondary: '#1F2937', // Gray 800
+  text: '#F9FAFB', // Gray 50
+  textSecondary: '#9CA3AF', // Gray 400
+  textPlaceholder: '#6B7280', // Gray 500
+  textOnPrimary: '#FFFFFF',
+  border: '#374151', // Gray 700
+  borderFocused: '#3B82F6', // Blue 500
+  error: '#EF4444', // Red 500
+  success: '#22C55E', // Green 500
+  warning: '#F59E0B', // Amber 500
+  info: '#3B82F6', // Blue 500
+  overlay: 'rgba(0, 0, 0, 0.5)',
+  overlayDark: 'rgba(0, 0, 0, 0.8)',
+  accent1: '#3B82F6', // Blue 500 (camera)
+  accent2: '#22C55E', // Green 500 (library)
+  accent3: '#F59E0B', // Amber 500 (files)
+};
+
+/**
+ * Default typography settings.
+ * Uses system font for maximum compatibility.
+ */
+export const defaultTypography: HarkenTypography = {
+  fontFamily: 'System',
+  fontFamilyHeading: undefined, // Falls back to fontFamily
+
+  titleSize: 20,
+  titleLineHeight: 1.3,
+  titleWeight: '600',
+
+  bodySize: 16,
+  bodyLineHeight: 1.5,
+  bodyWeight: 'normal',
+
+  labelSize: 14,
+  labelWeight: '500',
+
+  captionSize: 12,
+  captionWeight: 'normal',
+};
+
+/**
+ * Default spacing scale.
+ * Based on a 4px grid system.
+ */
+export const defaultSpacing: HarkenSpacing = {
+  xs: 4,
+  sm: 8,
+  md: 16,
+  lg: 24,
+  xl: 32,
+  xxl: 48,
+};
+
+/**
+ * Default border radius values.
+ */
+export const defaultRadii: HarkenRadii = {
+  none: 0,
+  sm: 4,
+  md: 8,
+  lg: 16,
+  xl: 20,
+  full: 9999,
+};
+
+/**
+ * Complete default light theme.
+ */
+export const lightTheme: HarkenTheme = {
+  colors: lightColors,
+  typography: defaultTypography,
+  spacing: defaultSpacing,
+  radii: defaultRadii,
+};
+
+/**
+ * Complete default dark theme.
+ */
+export const darkTheme: HarkenTheme = {
+  colors: darkColors,
+  typography: defaultTypography,
+  spacing: defaultSpacing,
+  radii: defaultRadii,
+};
+
+/**
+ * Creates a theme by merging overrides with a base theme.
+ */
+export function createTheme(
+  baseTheme: HarkenTheme,
+  overrides?: {
+    colors?: Partial<HarkenColors>;
+    typography?: Partial<HarkenTypography>;
+    spacing?: Partial<HarkenSpacing>;
+    radii?: Partial<HarkenRadii>;
+  }
+): HarkenTheme {
+  if (!overrides) {
+    return baseTheme;
+  }
+
+  return {
+    colors: { ...baseTheme.colors, ...overrides.colors },
+    typography: { ...baseTheme.typography, ...overrides.typography },
+    spacing: { ...baseTheme.spacing, ...overrides.spacing },
+    radii: { ...baseTheme.radii, ...overrides.radii },
+  };
+}

package/src/theme/index.ts

@@ -0,0 +1,23 @@
+// Theme type exports
+export type {
+  HarkenColors,
+  HarkenTypography,
+  HarkenSpacing,
+  HarkenRadii,
+  HarkenTheme,
+  PartialHarkenTheme,
+  TextWeight,
+  ThemeMode,
+} from './types';
+
+// Default theme exports
+export {
+  lightColors,
+  darkColors,
+  defaultTypography,
+  defaultSpacing,
+  defaultRadii,
+  lightTheme,
+  darkTheme,
+  createTheme,
+} from './defaults';

package/src/theme/types.ts

@@ -0,0 +1,157 @@
+/**
+ * Color tokens for Harken SDK theming.
+ * All colors support full override by host apps.
+ */
+export interface HarkenColors {
+  /** Primary brand color for buttons and accents */
+  primary: string;
+  /** Darker variant of primary for pressed states */
+  primaryPressed: string;
+  /** Background color for the feedback form */
+  background: string;
+  /** Secondary background (cards, inputs) */
+  backgroundSecondary: string;
+  /** Primary text color */
+  text: string;
+  /** Secondary/muted text color */
+  textSecondary: string;
+  /** Placeholder text color */
+  textPlaceholder: string;
+  /** Text color on primary-colored backgrounds */
+  textOnPrimary: string;
+  /** Border color for inputs and dividers */
+  border: string;
+  /** Focused border color */
+  borderFocused: string;
+  /** Error state color */
+  error: string;
+  /** Success state color */
+  success: string;
+  /** Warning state color */
+  warning: string;
+  /** Informational state color */
+  info: string;
+  /** Light overlay background (for modals, sheets) */
+  overlay: string;
+  /** Dark overlay background (for error states, loading) */
+  overlayDark: string;
+  /** Accent color 1 (e.g., camera option) */
+  accent1: string;
+  /** Accent color 2 (e.g., photo library option) */
+  accent2: string;
+  /** Accent color 3 (e.g., files option) */
+  accent3: string;
+}
+
+/**
+ * Typography tokens for Harken SDK theming.
+ * Allows complete font customization.
+ */
+export interface HarkenTypography {
+  /** Font family for body text */
+  fontFamily: string;
+  /** Font family for headings (defaults to fontFamily if not set) */
+  fontFamilyHeading?: string;
+
+  /** Title text size */
+  titleSize: number;
+  /** Title line height multiplier */
+  titleLineHeight: number;
+  /** Title font weight */
+  titleWeight: TextWeight;
+
+  /** Body text size */
+  bodySize: number;
+  /** Body line height multiplier */
+  bodyLineHeight: number;
+  /** Body font weight */
+  bodyWeight: TextWeight;
+
+  /** Label text size (for buttons, form labels) */
+  labelSize: number;
+  /** Label font weight */
+  labelWeight: TextWeight;
+
+  /** Caption/small text size */
+  captionSize: number;
+  /** Caption font weight */
+  captionWeight: TextWeight;
+}
+
+/** Font weight values supported across platforms */
+export type TextWeight =
+  | 'normal'
+  | 'bold'
+  | '100'
+  | '200'
+  | '300'
+  | '400'
+  | '500'
+  | '600'
+  | '700'
+  | '800'
+  | '900';
+
+/**
+ * Spacing tokens for consistent layout.
+ * All values are in logical pixels.
+ */
+export interface HarkenSpacing {
+  /** Extra small spacing (4px default) */
+  xs: number;
+  /** Small spacing (8px default) */
+  sm: number;
+  /** Medium spacing (16px default) */
+  md: number;
+  /** Large spacing (24px default) */
+  lg: number;
+  /** Extra large spacing (32px default) */
+  xl: number;
+  /** 2x extra large spacing (48px default) */
+  xxl: number;
+}
+
+/**
+ * Border radius tokens for rounded corners.
+ * All values are in logical pixels.
+ */
+export interface HarkenRadii {
+  /** No radius */
+  none: number;
+  /** Small radius for subtle rounding (4px default) */
+  sm: number;
+  /** Medium radius for inputs and cards (8px default) */
+  md: number;
+  /** Large radius for modals and sheets (16px default) */
+  lg: number;
+  /** Extra large radius for bottom sheets (20px default) */
+  xl: number;
+  /** Full/pill radius */
+  full: number;
+}
+
+/**
+ * Complete theme object combining all token types.
+ */
+export interface HarkenTheme {
+  colors: HarkenColors;
+  typography: HarkenTypography;
+  spacing: HarkenSpacing;
+  radii: HarkenRadii;
+}
+
+/**
+ * Partial theme for overriding specific values.
+ * Allows deep partial overrides of any theme token.
+ */
+export type PartialHarkenTheme = {
+  colors?: Partial<HarkenColors>;
+  typography?: Partial<HarkenTypography>;
+  spacing?: Partial<HarkenSpacing>;
+  radii?: Partial<HarkenRadii>;
+};
+
+/**
+ * Theme mode for automatic light/dark theming.
+ */
+export type ThemeMode = 'light' | 'dark' | 'system';