onecrew-api-client/README.md

OneCrew Backend API Client for Expo/React Native - A comprehensive TypeScript client for film and entertainment industry APIs with user profile management, talent profiles, skills, abilities, languages, portfolio management, project management, task assig

# OneCrew API Client

A TypeScript/JavaScript client library for the OneCrew Backend API, designed for Expo and React Native applications.

## Installation

```bash
npm install onecrew-api-client
```

## Quick Start

```typescript
import { OneCrewApi } from 'onecrew-api-client';

// Initialize the API client
const api = new OneCrewApi('https://your-api-url.com');

// Initialize authentication
await api.initialize();

// Example: Login and manage user details
await api.auth.login({ 
  email: 'user@example.com', 
  password: 'password' 
});

// Create user details
const userDetails = await api.createUserDetails({
  gender: 'female',
  age: 25,
  nationality: 'American',
  height_cm: 165,
  weight_kg: 58,
  skin_tone: 'medium',
  hair_color: 'brown',
  willing_to_travel: true
});

// Get user details
const details = await api.getUserDetails();
console.log('User details:', details.data);

// Example: Managing talent profile with dropdowns
const [hairColors, skinTones, profile] = await Promise.all([
  api.getAvailableHairColors(),
  api.getAvailableSkinTones(),
  api.getTalentProfile()
]);

// Create dropdown options with current selection
const hairColorOptions = hairColors.data.map(option => ({
  id: option.id,
  name: option.name,
  selected: option.id === profile.data.hair_color_id
}));

const skinToneOptions = skinTones.data.map(option => ({
  id: option.id,
  name: option.name,
  selected: option.id === profile.data.skin_tone_id
}));

// Update talent profile
await api.updateTalentProfile({
  hair_color_id: 'selected-hair-color-id',
  skin_tone_id: 'selected-skin-tone-id',
  eye_color: 'brown',
  height_cm: 175,
  weight_kg: 70
});
```

## Features

- 🔐 **Authentication**: JWT token management with secure storage
- 👥 **User Management**: Get, update, and manage user profiles
- 📋 **User Details**: Complete user profile details management
- 🎭 **Talent Profile**: Comprehensive talent profile management
- 🛠️ **Skills Management**: Add, remove, and manage user skills
- 🎯 **Abilities**: Manage abilities with proficiency levels
- 🌍 **Languages**: Multi-language support with proficiency levels
- 🖼️ **Portfolio**: Media portfolio management (images/videos)
- 🎬 **Project Management**: Create, join, and manage film projects
- 👥 **Team Management**: Create and manage teams
- 💬 **Communication**: Real-time messaging and conversations
- 🔍 **Search**: Advanced search across users, projects, and teams
- 📁 **File Upload**: Upload files and media
- 📱 **React Native Ready**: Optimized for Expo and React Native

## API Methods

### User Management
- `getUsers(params?)` - Get all users with filters
- `getUserById(userId)` - Get user by ID
- `getUserByIdDirect(userId)` - Direct user endpoint
- `updateUserProfile(updates)` - Update current user profile
- `deleteUser()` - Delete current user

### User Details Management
- `getUserDetails(userId?)` - Get user details (current user or by ID)
- `createUserDetails(details)` - Create user details
- `updateUserDetails(updates)` - Update current user's details
- `updateUserDetailsById(userId, updates)` - Update specific user's details
- `patchUserDetails(updates)` - Partial update of current user's details
- `deleteUserDetails(userId?)` - Delete user details

### Talent Profile Management
- `getTalentProfile()` - Get current user's talent profile
- `updateTalentProfile(updates)` - Update talent profile
- `patchTalentProfile(updates)` - Partial update of talent profile
- `getAvailableHairColors()` - Get all available hair colors for dropdowns
- `getAvailableSkinTones()` - Get all available skin tones for dropdowns

### Skills Management
- `getAvailableSkills()` - Get all available skills
- `getUserSkills()` - Get user's current skills
- `addUserSkill(skillId)` - Add skill to user profile
- `removeUserSkill(skillId)` - Remove skill from user profile

### Abilities Management
- `getAvailableAbilities()` - Get all available abilities
- `getUserAbilities()` - Get user's current abilities
- `addUserAbility(abilityId, proficiency)` - Add ability with proficiency (1-5)
- `updateUserAbility(abilityId, proficiency)` - Update ability proficiency
- `removeUserAbility(abilityId)` - Remove ability from user profile

### Languages Management
- `getAvailableLanguages()` - Get all available languages
- `getUserLanguages()` - Get user's current languages
- `addUserLanguage(languageId, level)` - Add language with proficiency level
- `removeUserLanguage(languageId)` - Remove language from user profile

### Portfolio Management
- `getUserPortfolio()` - Get user's portfolio items
- `addPortfolioItem(item)` - Add image/video to portfolio
- `updatePortfolioItem(itemId, updates)` - Update portfolio item
- `removePortfolioItem(itemId)` - Remove portfolio item

### Project Management
- `getProjects(params?)` - Get all projects
- `getProjectById(projectId)` - Get project by ID
- `createProject(projectData)` - Create new project
- `updateProject(projectId, updates)` - Update project
- `joinProject(projectId, role?)` - Join a project
- `leaveProject(projectId)` - Leave a project

### Team Management
- `getTeams(params?)` - Get all teams
- `getTeamById(teamId)` - Get team by ID
- `createTeam(teamData)` - Create new team
- `joinTeam(teamData)` - Join a team
- `leaveTeam(teamId)` - Leave a team

### Communication
- `getConversations(params?)` - Get user conversations
- `createConversation(participantIds, name?)` - Create conversation
- `getMessages(conversationId, params?)` - Get conversation messages
- `sendMessage(conversationId, messageData)` - Send message

### Search
- `searchUsers(params)` - Search users
- `searchProjects(params)` - Search projects
- `searchTeams(params)` - Search teams
- `globalSearch(query, params?)` - Global search
- `getSearchSuggestions(query)` - Get search suggestions

### File Upload
- `uploadFile(file)` - Upload file

## Examples

### Talent Profile Management

```typescript
// Get talent profile
const talentProfile = await api.getTalentProfile();
console.log('Talent profile:', talentProfile.data);

// Update talent profile
const updatedProfile = await api.updateTalentProfile({
  height_cm: 175,
  weight_kg: 70,
  eye_color: 'brown',
  travel_ready: true,
  union_member: false
});
```

### Skills Management

```typescript
// Get available skills
const availableSkills = await api.getAvailableSkills();
console.log('Available skills:', availableSkills.data);

// Get user's current skills
const userSkills = await api.getUserSkills();
console.log('User skills:', userSkills.data);

// Add a skill to user profile
const skillToAdd = availableSkills.data[0];
const addedSkill = await api.addUserSkill(skillToAdd.id);
console.log('Added skill:', addedSkill.data);

// Remove a skill from user profile
await api.removeUserSkill(skillToAdd.id);
```

### Abilities Management

```typescript
// Get available abilities
const availableAbilities = await api.getAvailableAbilities();
console.log('Available abilities:', availableAbilities.data);

// Add ability with proficiency level (1-5)
const abilityToAdd = availableAbilities.data[0];
const addedAbility = await api.addUserAbility(abilityToAdd.id, 4);
console.log('Added ability:', addedAbility.data);

// Update ability proficiency
await api.updateUserAbility(abilityToAdd.id, 5);
```

### Languages Management

```typescript
// Get available languages
const availableLanguages = await api.getAvailableLanguages();
console.log('Available languages:', availableLanguages.data);

// Add language with proficiency level
const languageToAdd = availableLanguages.data[0];
const addedLanguage = await api.addUserLanguage(languageToAdd.id, 'native');
console.log('Added language:', addedLanguage.data);
```

### Portfolio Management

```typescript
// Get user's portfolio
const portfolio = await api.getUserPortfolio();
console.log('Portfolio items:', portfolio.data);

// Add portfolio item
const newItem = await api.addPortfolioItem({
  kind: 'image',
  url: 'https://example.com/image.jpg',
  caption: 'My headshot',
  sort_order: 1
});
console.log('Added portfolio item:', newItem.data);

// Update portfolio item
await api.updatePortfolioItem(newItem.data.id, {
  caption: 'Updated headshot caption',
  sort_order: 2
});
```

## Configuration

```typescript
const api = new OneCrewApi(
  'https://your-api-url.com', // Base URL
  30000, // Timeout in milliseconds (optional)
  3 // Number of retries (optional)
);
```

## Authentication

The client automatically handles JWT token storage and refresh:

```typescript
// Login
const authResponse = await api.auth.login({
  email: 'user@example.com',
  password: 'password'
});

// Check if user is authenticated
const isAuthenticated = await api.auth.isAuthenticated();

// Logout
await api.auth.logout();
```

## Error Handling

All methods return a consistent response format:

```typescript
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

// Example usage
const response = await api.getUserById('user-id');
if (response.success) {
  console.log('User data:', response.data);
} else {
  console.error('Error:', response.error);
}
```

## TypeScript Support

Full TypeScript support with comprehensive type definitions for all API responses and request parameters.

## License

MIT

## Support

For support and questions, please contact the OneCrew team.