@cranberry-money/shared-services 1.0.0

package/README.md

@@ -0,0 +1,288 @@
+# @myportfolio/shared-services
+
+Shared API services and client abstractions for the MyPortfolio platform, supporting both web (Blueberry) and mobile (Blackberry) applications.
+
+## Installation
+
+```bash
+npm install @myportfolio/shared-services
+```
+
+## Core Architecture
+
+This package provides a platform-agnostic API client architecture with:
+
+- **Token Storage Abstraction**: Secure token management across platforms
+- **Base API Client**: Common HTTP request interface  
+- **Platform Adapters**: Web (cookies) and Mobile (secure storage) implementations
+- **Offline Support**: Request queuing and retry logic for mobile
+- **Authentication Handling**: Automatic token refresh and error handling
+
+## Usage
+
+### Web Implementation
+
+```typescript
+import { WebApiClient, WebTokenStorage } from '@myportfolio/shared-services';
+
+// Create web API client with cookie-based auth
+const apiClient = new WebApiClient({
+  baseURL: 'https://api.myportfolio.com',
+  withCredentials: true, // Enable cookies
+});
+
+// Set up token storage (optional for cookie-based auth)
+const tokenStorage = new WebTokenStorage();
+apiClient.setTokenStorage(tokenStorage);
+
+// Make requests
+const response = await apiClient.get('/auth/profile');
+const data = await apiClient.post('/portfolios', { name: 'My Portfolio' });
+```
+
+### Mobile Implementation
+
+```typescript
+import { 
+  MobileApiClient, 
+  MobileTokenStorage, 
+  createExpoSecureStoreAdapter 
+} from '@myportfolio/shared-services';
+
+// Create mobile API client with secure token storage  
+const apiClient = new MobileApiClient({
+  baseURL: 'https://api.myportfolio.com',
+  retryAttempts: 3,
+  offlineQueueEnabled: true,
+});
+
+// Set up secure token storage
+const secureStore = createExpoSecureStoreAdapter();
+const tokenStorage = new MobileTokenStorage(secureStore);
+apiClient.setTokenStorage(tokenStorage);
+
+// Handle network state
+apiClient.setNetworkState(isOnline);
+
+// Make requests with automatic retry and offline queueing
+const response = await apiClient.get('/auth/profile');
+```
+
+## Core Components
+
+### TokenStorage Interface
+
+Provides secure, cross-platform token management:
+
+```typescript
+interface TokenStorage {
+  storeTokens(tokens: { access: string; refresh: string }): Promise<void>;
+  retrieveTokens(): Promise<{ access: string; refresh: string } | null>;
+  clearTokens(): Promise<void>;
+  hasTokens(): Promise<boolean>;
+}
+```
+
+**Implementations:**
+- `WebTokenStorage` - HTTP-only cookies (web)
+- `MobileTokenStorage` - Secure device storage (mobile)
+
+### BaseApiClient
+
+Abstract base class providing common API functionality:
+
+```typescript
+abstract class BaseApiClient {
+  // HTTP methods
+  get<T>(url: string, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+  post<T>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+  put<T>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+  patch<T>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+  delete<T>(url: string): Promise<ApiResponse<T>>;
+  
+  // Configuration
+  setTokenStorage(storage: TokenStorage): void;
+  
+  // Abstract methods (implemented by platform adapters)
+  abstract request<T>(config: RequestConfig): Promise<ApiResponse<T>>;
+}
+```
+
+## Platform Adapters
+
+### Web Adapter (`WebApiClient`)
+
+Optimized for browser environments:
+
+- **Cookie-based authentication** with `withCredentials` support
+- **CORS handling** for cross-origin requests
+- **Fetch API** based implementation
+- **Content-type detection** for response parsing
+- **Token refresh** via `/auth/refresh` endpoint
+
+### Mobile Adapter (`MobileApiClient`)
+
+Enhanced for React Native with mobile-specific features:
+
+- **Retry logic** with exponential backoff
+- **Offline queue** for when network is unavailable  
+- **Network state awareness** with automatic queue processing
+- **Timeout handling** with AbortSignal
+- **Secure token storage** integration
+- **Battery-conscious** request batching
+
+## Authentication Flow
+
+### Web (Cookie-based)
+1. User signs in → Server sets HTTP-only cookies
+2. API requests automatically include cookies
+3. Token refresh handled by server cookie renewal
+4. Sign out clears cookies on server
+
+### Mobile (Token-based)
+1. User signs in → Tokens stored in secure storage
+2. API requests include `Authorization: Bearer <token>` header
+3. Automatic token refresh with secure storage update
+4. Sign out clears tokens from secure storage
+
+## Error Handling
+
+Consistent error handling across platforms:
+
+```typescript
+interface ApiError {
+  message: string;
+  status?: number;
+  code?: string;
+  data?: unknown;
+}
+
+// Error codes
+'NETWORK_ERROR'    // Network connectivity issues
+'TIMEOUT_ERROR'    // Request timeout
+'HTTP_ERROR'       // HTTP status errors (4xx, 5xx)
+'UNAUTHORIZED'     // Authentication failure
+'UNEXPECTED_ERROR' // Unknown errors
+```
+
+## Offline Support (Mobile)
+
+```typescript
+// Enable offline queue
+const client = new MobileApiClient({ 
+  offlineQueueEnabled: true 
+});
+
+// Set network state
+client.setNetworkState(false); // Requests queued
+client.setNetworkState(true);  // Queue processed
+
+// Manual sync
+await client.syncWhenOnline();
+```
+
+## Token Storage Security
+
+### Web Security
+- HTTP-only cookies prevent XSS attacks
+- SameSite cookie attributes prevent CSRF
+- Secure flag for HTTPS-only transmission
+- Server-side session management
+
+### Mobile Security  
+- iOS Keychain / Android Keystore integration
+- Hardware-backed encryption when available
+- Automatic data protection classes  
+- Secure deletion on app uninstall
+
+## React Query Integration
+
+The package is designed to work seamlessly with React Query:
+
+```typescript
+// Custom hook example
+function useProfile() {
+  return useQuery({
+    queryKey: ['profile'],
+    queryFn: () => apiClient.get('/auth/profile'),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
+}
+
+// Mutation example
+function useSignIn() {
+  return useMutation({
+    mutationFn: (credentials) => apiClient.post('/auth/signin', credentials),
+    onSuccess: (response) => {
+      // Handle successful authentication
+    },
+  });
+}
+```
+
+## Configuration
+
+### Web Configuration
+```typescript
+const client = new WebApiClient({
+  baseURL: 'https://api.myportfolio.com',
+  timeout: 30000,
+  withCredentials: true,
+  defaultHeaders: {
+    'X-Client-Version': '1.0.0',
+  },
+});
+```
+
+### Mobile Configuration
+```typescript
+const client = new MobileApiClient({
+  baseURL: 'https://api.myportfolio.com', 
+  timeout: 30000,
+  retryAttempts: 3,
+  retryDelay: 1000,
+  offlineQueueEnabled: true,
+  defaultHeaders: {
+    'X-Client-Version': '1.0.0',
+    'X-Platform': 'mobile',
+  },
+});
+```
+
+## Development
+
+```bash
+# Build the package
+npm run build
+
+# Watch for changes
+npm run dev
+
+# Type check
+npm run typecheck
+```
+
+## Dependencies
+
+- `@myportfolio/shared-types` - Shared type definitions
+- `@myportfolio/shared-constants` - HTTP constants and headers
+
+## Peer Dependencies
+
+- `@tanstack/react-query` - For React Query integration (optional)
+- `typescript` - For TypeScript support
+
+## Platform Requirements
+
+### Web
+- Modern browsers with Fetch API support
+- Cookie support for authentication
+
+### Mobile  
+- React Native 0.60+ 
+- Expo SDK 47+ (for Expo SecureStore)
+- iOS 10+ / Android API 21+
+
+## License
+
+MIT

package/dist/adapters/MobileApiClient.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Mobile-specific API client implementation
+ *
+ * This implementation is designed for React Native environments
+ * and includes mobile-specific features like network state awareness,
+ * offline capability, and retry logic.
+ */
+import { BaseApiClient, type RequestConfig, type ApiResponse, type ApiClientConfig } from '../core/BaseApiClient';
+export interface MobileApiClientConfig extends ApiClientConfig {
+    retryAttempts?: number;
+    retryDelay?: number;
+    offlineQueueEnabled?: boolean;
+}
+export declare class MobileApiClient extends BaseApiClient {
+    private retryAttempts;
+    private retryDelay;
+    private offlineQueueEnabled;
+    private offlineQueue;
+    private isOnline;
+    constructor(config: MobileApiClientConfig);
+    request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
+    private executeRequest;
+    /**
+     * Queue request for when back online
+     */
+    private queueRequest;
+    /**
+     * Process offline queue when back online
+     */
+    syncWhenOnline(): Promise<void>;
+    /**
+     * Enable offline mode
+     */
+    enableOfflineMode(): void;
+    /**
+     * Enable online mode and sync queue
+     */
+    enableOnlineMode(): Promise<void>;
+    /**
+     * Set network state
+     */
+    setNetworkState(isOnline: boolean): void;
+    /**
+     * Parse response data based on content type
+     */
+    private parseResponseData;
+    /**
+     * Convert Headers to plain object
+     */
+    private parseResponseHeaders;
+    /**
+     * Check if error is an API error
+     */
+    private isApiError;
+    /**
+     * Determine if request should be retried
+     */
+    private shouldRetry;
+    /**
+     * Handle token refresh for mobile (secure storage based)
+     */
+    protected handleTokenRefresh(): Promise<boolean>;
+    /**
+     * Utility delay function
+     */
+    private delay;
+}
+//# sourceMappingURL=MobileApiClient.d.ts.map

package/dist/adapters/MobileApiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MobileApiClient.d.ts","sourceRoot":"","sources":["../../src/adapters/MobileApiClient.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAElH,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,qBAAa,eAAgB,SAAQ,aAAa;IAChD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,mBAAmB,CAAU;IACrC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,QAAQ,CAAiB;gBAErB,MAAM,EAAE,qBAAqB;IAcnC,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAS5D,cAAc;IAwF5B;;OAEG;YACW,YAAY;IAU1B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBrC;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAIzB;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAOvC;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAUxC;;OAEG;YACW,iBAAiB;IAe/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;OAEG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,OAAO,CAAC,WAAW;IAsBnB;;OAEG;cACa,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC;IAyBtD;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd"}

package/dist/adapters/MobileApiClient.js

@@ -0,0 +1,240 @@
+/**
+ * Mobile-specific API client implementation
+ *
+ * This implementation is designed for React Native environments
+ * and includes mobile-specific features like network state awareness,
+ * offline capability, and retry logic.
+ */
+import { HTTP_HEADER_CONTENT_TYPE, CONTENT_TYPE_APPLICATION_JSON } from '@myportfolio/shared-constants';
+import { BaseApiClient } from '../core/BaseApiClient';
+export class MobileApiClient extends BaseApiClient {
+    constructor(config) {
+        super({
+            ...config,
+            defaultHeaders: {
+                [HTTP_HEADER_CONTENT_TYPE]: CONTENT_TYPE_APPLICATION_JSON,
+                ...config.defaultHeaders,
+            },
+        });
+        this.offlineQueue = [];
+        this.isOnline = true;
+        this.retryAttempts = config.retryAttempts || 3;
+        this.retryDelay = config.retryDelay || 1000;
+        this.offlineQueueEnabled = config.offlineQueueEnabled || false;
+    }
+    async request(config) {
+        // Check if we're offline and should queue the request
+        if (!this.isOnline && this.offlineQueueEnabled) {
+            return this.queueRequest(config);
+        }
+        return this.executeRequest(config);
+    }
+    async executeRequest(config, attempt = 1) {
+        const url = this.buildUrl(config.url);
+        const headers = await this.buildHeaders(config.headers);
+        // Build fetch options
+        const fetchOptions = {
+            method: config.method || 'GET',
+            headers,
+            signal: config.timeout ? AbortSignal.timeout(config.timeout) : undefined,
+        };
+        // Add body for non-GET requests
+        if (config.data && config.method !== 'GET') {
+            if (headers[HTTP_HEADER_CONTENT_TYPE] === CONTENT_TYPE_APPLICATION_JSON) {
+                fetchOptions.body = JSON.stringify(config.data);
+            }
+            else {
+                fetchOptions.body = config.data;
+            }
+        }
+        // Add query parameters for GET requests
+        const requestUrl = config.params && config.method === 'GET'
+            ? `${url}?${new URLSearchParams(config.params).toString()}`
+            : url;
+        try {
+            const response = await fetch(requestUrl, fetchOptions);
+            // Handle non-2xx responses
+            if (!response.ok) {
+                const errorData = await this.parseResponseData(response);
+                // Handle authentication errors
+                if (response.status === 401) {
+                    const refreshed = await this.handleTokenRefresh();
+                    if (refreshed && attempt === 1) {
+                        // Retry once with new token
+                        return this.executeRequest(config, attempt + 1);
+                    }
+                }
+                throw this.createError(response.statusText || 'Request failed', response.status, 'HTTP_ERROR', errorData);
+            }
+            const data = await this.parseResponseData(response);
+            return {
+                data,
+                status: response.status,
+                statusText: response.statusText,
+                headers: this.parseResponseHeaders(response.headers),
+            };
+        }
+        catch (error) {
+            // Handle network errors with retry logic
+            if (this.shouldRetry(error, attempt)) {
+                await this.delay(this.retryDelay * attempt); // Exponential backoff
+                return this.executeRequest(config, attempt + 1);
+            }
+            // Handle different error types
+            if (error instanceof TypeError && error.message.includes('fetch')) {
+                throw this.createError('Network error', 0, 'NETWORK_ERROR');
+            }
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                throw this.createError('Request timeout', 0, 'TIMEOUT_ERROR');
+            }
+            // Re-throw API errors
+            if (this.isApiError(error)) {
+                throw error;
+            }
+            // Handle unexpected errors
+            throw this.createError(error instanceof Error ? error.message : 'Unknown error', 0, 'UNEXPECTED_ERROR');
+        }
+    }
+    /**
+     * Queue request for when back online
+     */
+    async queueRequest(config) {
+        return new Promise((resolve, reject) => {
+            this.offlineQueue.push({
+                ...config,
+                resolve: resolve,
+                reject,
+            });
+        });
+    }
+    /**
+     * Process offline queue when back online
+     */
+    async syncWhenOnline() {
+        if (!this.isOnline || this.offlineQueue.length === 0)
+            return;
+        const queue = [...this.offlineQueue];
+        this.offlineQueue = [];
+        for (const request of queue) {
+            try {
+                const response = await this.executeRequest(request);
+                request.resolve(response);
+            }
+            catch (error) {
+                request.reject(error);
+            }
+        }
+    }
+    /**
+     * Enable offline mode
+     */
+    enableOfflineMode() {
+        this.isOnline = false;
+    }
+    /**
+     * Enable online mode and sync queue
+     */
+    async enableOnlineMode() {
+        this.isOnline = true;
+        if (this.offlineQueueEnabled) {
+            await this.syncWhenOnline();
+        }
+    }
+    /**
+     * Set network state
+     */
+    setNetworkState(isOnline) {
+        const wasOffline = !this.isOnline;
+        this.isOnline = isOnline;
+        if (wasOffline && isOnline && this.offlineQueueEnabled) {
+            // Process queue when coming back online
+            this.syncWhenOnline().catch(console.error);
+        }
+    }
+    /**
+     * Parse response data based on content type
+     */
+    async parseResponseData(response) {
+        const contentType = response.headers.get('content-type') || '';
+        if (contentType.includes('application/json')) {
+            return response.json();
+        }
+        if (contentType.includes('text/')) {
+            return response.text();
+        }
+        // For other content types, return as blob
+        return response.blob();
+    }
+    /**
+     * Convert Headers to plain object
+     */
+    parseResponseHeaders(headers) {
+        const headerObj = {};
+        headers.forEach((value, key) => {
+            headerObj[key] = value;
+        });
+        return headerObj;
+    }
+    /**
+     * Check if error is an API error
+     */
+    isApiError(error) {
+        return typeof error === 'object' &&
+            error !== null &&
+            'message' in error &&
+            'status' in error;
+    }
+    /**
+     * Determine if request should be retried
+     */
+    shouldRetry(error, attempt) {
+        if (attempt >= this.retryAttempts)
+            return false;
+        // Retry on network errors
+        if (error instanceof TypeError && error.message.includes('fetch')) {
+            return true;
+        }
+        // Retry on timeout errors
+        if (error instanceof DOMException && error.name === 'AbortError') {
+            return true;
+        }
+        // Retry on certain HTTP status codes
+        if (this.isApiError(error)) {
+            const status = error.status;
+            return status === 429 || (status !== undefined && status >= 500); // Rate limit or server errors
+        }
+        return false;
+    }
+    /**
+     * Handle token refresh for mobile (secure storage based)
+     */
+    async handleTokenRefresh() {
+        if (!this.tokenStorage)
+            return false;
+        try {
+            const tokens = await this.tokenStorage.retrieveTokens();
+            if (!tokens?.refresh)
+                return false;
+            const response = await this.request({
+                url: '/auth/refresh',
+                method: 'POST',
+                data: { refresh: tokens.refresh },
+            });
+            if (response.status === 200 && response.data) {
+                const newTokens = response.data;
+                await this.tokenStorage.storeTokens(newTokens);
+                return true;
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Utility delay function
+     */
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}

package/dist/adapters/MobileTokenStorage.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mobile-specific token storage using secure storage
+ *
+ * This implementation uses platform-secure storage mechanisms
+ * like iOS Keychain and Android Keystore via React Native libraries.
+ *
+ * For Expo: Uses Expo SecureStore
+ * For bare React Native: Would use @react-native-async-storage/async-storage
+ * with encryption or react-native-keychain
+ */
+import { BaseTokenStorage, type TokenPair } from '../core/TokenStorage';
+export declare class MobileTokenStorage extends BaseTokenStorage {
+    private secureStore;
+    constructor(secureStore: SecureStoreInterface);
+    storeTokens(tokens: TokenPair): Promise<void>;
+    retrieveTokens(): Promise<TokenPair | null>;
+    clearTokens(): Promise<void>;
+    hasTokens(): Promise<boolean>;
+    /**
+     * Check if secure storage is available
+     */
+    isAvailable(): Promise<boolean>;
+}
+/**
+ * Interface for secure storage implementations
+ * This abstracts the specific secure storage library being used
+ */
+export interface SecureStoreInterface {
+    setItemAsync(key: string, value: string): Promise<void>;
+    getItemAsync(key: string): Promise<string | null>;
+    deleteItemAsync(key: string): Promise<void>;
+    isAvailableAsync?(): Promise<boolean>;
+}
+/**
+ * Factory function to create MobileTokenStorage with different backends
+ */
+export declare const createMobileTokenStorage: (secureStore: SecureStoreInterface) => MobileTokenStorage;
+/**
+ * Expo SecureStore adapter
+ * Usage: createMobileTokenStorage(createExpoSecureStoreAdapter())
+ */
+export declare const createExpoSecureStoreAdapter: () => SecureStoreInterface;
+//# sourceMappingURL=MobileTokenStorage.d.ts.map

package/dist/adapters/MobileTokenStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MobileTokenStorage.d.ts","sourceRoot":"","sources":["../../src/adapters/MobileTokenStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAQxE,qBAAa,kBAAmB,SAAQ,gBAAgB;IACtD,OAAO,CAAC,WAAW,CAAuB;gBAE9B,WAAW,EAAE,oBAAoB;IAKvC,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7C,cAAc,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA0B3C,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAanC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAStC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAClD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,gBAAgB,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,GAAI,aAAa,oBAAoB,KAAG,kBAE5E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAAO,oBAsB/C,CAAC"}