OneCrew API Client

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

Installation

npm install onecrew-api-client

Quick Start

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: '[email protected]', 
  password: 'password' 
});

// Create user details
const userDetails = await api.createUserDetails({
  gender: 'female',
  birthday: '1998-05-15', // Date string in ISO format (YYYY-MM-DD)
  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
• 🔔 Push Notifications: iOS and Android push notification support
• 🔍 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
• getMyProjects(params?) - Get user's projects (supports include_deleted parameter)
• getDeletedProjects(params?) - Get user's deleted projects only
• deleteProject(projectId) - Soft delete a project
• restoreProject(projectId) - Restore a soft-deleted 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

Chat (Real-Time Chat System)

Use api.chat.* for the newer chat system (/api/chat/...). This supports sender/read hydration controls to keep responses small and avoid over-fetching.

• chat.getMessages(conversationId, params?) - Get conversation messages (supports include, sender_type, sender_user_fields, sender_company_fields)
• chat.sendMessage(conversationId, data) - Send a message
• chat.getConversations(params?) - List conversations

Examples

// Profile-scoped conversation lists (avoid mixing personal + company chats)
const personalConversations = await api.chat.getConversations({ profile_type: 'user' });
const companyConversations = await api.chat.getConversations({ profile_type: 'company' });
const singleCompanyConversations = await api.chat.getConversations({
  profile_type: 'company',
  company_id: 'your-company-id'
});

// Personal messages only, no extra hydration (smallest payload)
const personal = await api.chat.getMessages(conversationId, {
  sender_type: 'user',
  include: 'none'
});

// Company messages (includes academy) with academy detection
const company = await api.chat.getMessages(conversationId, {
  sender_type: 'company',
  include: ['sender_company'],
  sender_company_fields: ['id', 'name', 'logo_url', 'subcategory']
});

// Detect academy messages on the client
const academyMessages = (company.data?.data || []).filter(
  m => m.sender_company?.subcategory === 'academy'
);

Push Notifications

• pushNotifications.registerDeviceToken(token, platform, deviceId?, appVersion?) - Register device token for push notifications
• pushNotifications.unregisterDeviceToken(token) - Unregister device token
• pushNotifications.getDeviceTokens() - Get user's registered device tokens

Example:

// Register device token after login
import * as Notifications from 'expo-notifications';
import { Platform } from 'react-native';

// Get push token (Expo)
const { data: token } = await Notifications.getExpoPushTokenAsync({
  projectId: 'your-project-id'
});

// Register with backend
await api.pushNotifications.registerDeviceToken(
  token,
  Platform.OS === 'ios' ? 'ios' : 'android',
  'device-id-123',
  '1.0.0'
);

// Unregister on logout
await api.pushNotifications.unregisterDeviceToken(token);

See CLIENT_PUSH_NOTIFICATION_INTEGRATION.md for complete integration guide.

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

// 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

// 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

// 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

// 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

// 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
});

Account Deletion with Grace Period

// Request account deletion (requires password confirmation)
const deletionRequest = await api.requestAccountDeletion('your-password');
console.log('Deletion requested');
console.log('Expiration date:', deletionRequest.data?.expirationDate);
console.log('Days remaining:', deletionRequest.data?.daysRemaining);

// Check deletion status
const status = await api.getAccountDeletionStatus();
if (status.data?.isPending) {
  console.log('Account deletion pending');
  console.log('Days remaining:', status.data.daysRemaining);
}

// Restore account within grace period
if (status.data?.isPending && status.data.daysRemaining > 0) {
  await api.restoreAccount();
  console.log('Account restored successfully');
}

Configuration

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:

// Login
const authResponse = await api.auth.login({
  email: '[email protected]',
  password: 'password'
});

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

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

Google Sign-In (Supabase OAuth)

Google sign-in now uses Supabase OAuth. You must first authenticate with Supabase, then send the access token to the backend:

import { createClient } from '@supabase/supabase-js';

// Initialize Supabase client
const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
);

// Option 1: Using signInWithOAuth (redirect flow)
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'yourapp://auth/callback'
  }
});

// After OAuth completes, get the session
const { data: { session } } = await supabase.auth.getSession();

// Send Supabase access token to backend
if (session) {
  const authResponse = await api.auth.signInWithGoogle(
    session.access_token,
    'crew', // category (required for new users)
    'director' // primary_role (optional)
  );
}

// Option 2: Using signInWithIdToken (if using Google Sign-In SDK)
const { data, error } = await supabase.auth.signInWithIdToken({
  provider: 'google',
  token: googleIdToken
});

if (data.session) {
  await api.auth.signInWithGoogle(data.session.access_token, 'crew');
}

Note: Make sure Google OAuth is configured in your Supabase Dashboard (Authentication > Providers > Google).

Apple Sign-In (Supabase OAuth)

Apple sign-in uses Supabase OAuth. You must first authenticate with Supabase, then send the access token to the backend:

import { createClient } from '@supabase/supabase-js';

// Initialize Supabase client
const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
);

// Option 1: Using signInWithOAuth (redirect flow)
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'apple',
  options: {
    redirectTo: 'yourapp://auth/callback'
  }
});

// After OAuth completes, get the session
const { data: { session } } = await supabase.auth.getSession();

// Send Supabase access token to backend
if (session) {
  const authResponse = await api.auth.signInWithApple(
    session.access_token,
    'crew', // category (required for new users)
    'director' // primary_role (optional)
  );
}

// Option 2: Using signInWithIdToken (if using native Apple Sign-In SDK)
const { data, error } = await supabase.auth.signInWithIdToken({
  provider: 'apple',
  token: appleIdToken,
  nonce: rawNonce
});

if (data.session) {
  await api.auth.signInWithApple(data.session.access_token, 'crew');
}

Note: Make sure Apple OAuth is configured in your Supabase Dashboard (Authentication > Providers > Apple). You'll need an Apple Developer account and Service ID setup.

Error Handling

All methods return a consistent response format:

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.