Kordant/packages/mobile-api-client/README.md

# @shieldai/mobile-api-client

React Native API client library for ShieldAI services. Provides type-safe access to all API endpoints with built-in authentication, offline support, and error handling.

## Installation

```bash
npm install @shieldai/mobile-api-client
# or
yarn add @shieldai/mobile-api-client
```

## Setup

### Initialize the client

```typescript
import { createApiClient } from '@shieldai/mobile-api-client';

createApiClient({
  baseURL: 'https://api.shieldai.freno.me/api/v1',
  timeout: 30000,
  debug: __DEV__, // Enable debug logging in development
});
```

### Authentication

```typescript
import { authService } from '@shieldai/mobile-api-client';

// Login
const { user, tokens } = await authService.login({
  email: 'user@example.com',
  password: 'password123',
});

// Register
const { user: newUser } = await authService.register({
  email: 'user@example.com',
  password: 'password123',
  firstName: 'John',
  lastName: 'Doe',
});

// Get current user
const currentUser = await authService.getCurrentUser();

// Logout
await authService.logout();

// Check authentication status
const isAuthenticated = await authService.isAuthenticated();
```

### Device Management

```typescript
import { deviceService } from '@shieldai/mobile-api-client';
import * as Notifications from 'expo-notifications';

// Register device for push notifications
async function registerForPushNotifications() {
  const token = (await Notifications.getExpoPushTokenAsync({
    projectId: 'your-project-id',
  })).data;

  await deviceService.registerDevice({
    platform: Platform.OS === 'ios' ? 'ios' : 'android',
    pushToken: token,
    modelName: Platform.OS === 'ios' ? 'iPhone' : 'Android',
    osVersion: Platform.Version.toString(),
    appVersion: '1.0.0',
  });
}

// Get all user devices
const { devices } = await deviceService.getDevices();

// Update push token
await deviceService.updatePushToken('new-token');
```

### Subscriptions

```typescript
import { subscriptionService } from '@shieldai/mobile-api-client';

// Get current subscription
const { subscription, tier, usage } = await subscriptionService.getSubscription();

// Get available tiers
const tiers = await subscriptionService.getTiers();

// Create subscription
const newSubscription = await subscriptionService.createSubscription({
  tier: 'premium',
});

// Update subscription
await subscriptionService.updateSubscription({
  tier: 'enterprise',
});

// Cancel subscription
await subscriptionService.cancelSubscription();

// Create checkout session
const { url } = await subscriptionService.createCheckoutSession('premium');
Linking.openURL(url);

// Create customer portal session
const { url: portalUrl } = await subscriptionService.createCustomerPortalSession();
Linking.openURL(portalUrl);
```

### Notifications

```typescript
import { notificationService } from '@shieldai/mobile-api-client';

// Get notifications
const { notifications, unreadCount } = await notificationService.getNotifications({
  page: 1,
  limit: 20,
  unreadOnly: false,
});

// Mark as read
await notificationService.markAsRead(notificationId);

// Mark all as read
await notificationService.markAllAsRead();

// Get unread count
const count = await notificationService.getUnreadCount();

// Update preferences
await notificationService.updatePreferences({
  emailNotifications: true,
  pushNotifications: true,
  notificationTypes: {
    darkwatch_alert: true,
    spam_blocked: true,
    voiceprint_analysis: true,
  },
});
```

## Features

### Automatic Token Refresh

The client automatically handles JWT token refresh when access tokens expire:

```typescript
// No manual handling needed - just make the request
const user = await authService.getCurrentUser();
// If token expired, it will be refreshed automatically
```

### Offline Support

Requests are automatically queued when offline and replayed when connection is restored:

```typescript
import { requestQueue } from '@shieldai/mobile-api-client';

// Subscribe to queue status changes
const unsubscribe = requestQueue.subscribe(() => {
  const status = requestQueue.getStatus();
  console.log(`Queued requests: ${status.size}`);
});

// Cleanup
unsubscribe();
```

### Error Handling

```typescript
import { authService } from '@shieldai/mobile-api-client';

try {
  await authService.login({ email, password });
} catch (error) {
  if (error.response?.status === 401) {
    // Invalid credentials
  } else if (error.response?.status === 422) {
    // Validation error
  } else if (error.offline) {
    // Offline mode - request queued
  } else {
    // Network error
  }
}
```

## API Reference

### Services

- `authService` - Authentication and user management
- `deviceService` - Device registration and push tokens
- `subscriptionService` - Billing and subscription management
- `notificationService` - Push notifications and preferences

### Types

All TypeScript types are exported for type-safe development:

```typescript
import type { User, Device, Subscription, Notification } from '@shieldai/mobile-api-client';
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Type check
npx tsc --noEmit

# Lint
npm run lint
```

## License

MIT