node-behind-api-client 2.0.48

package/docs/behind-api-client/easyjob/applications/README.md

@@ -0,0 +1,754 @@
+# Applications API Extension
+
+This document extends the main EasyJob JavaScript API Client Documentation with detailed information about the Applications API methods.
+
+## Overview
+
+The Applications API allows you to manage job applications and interact with application-related data throughout the hiring process. This includes creating new applications, retrieving existing applications, getting application questions, and managing the application workflow.
+
+---
+
+## Applications API
+
+### behindAPI.easyjob.V10.applications.create(candidateProfileId, jobDescriptionId, message)
+Creates a new job application for a candidate applying to a specific job posting.
+
+**Parameters:**
+- `candidateProfileId` (string, required) - The candidate profile UUID who is applying
+- `jobDescriptionId` (string, required) - The job description UUID they are applying for
+- `message` (string, optional) - Optional cover letter or application message from the candidate
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.applications.create(
+    "aa0e8400-e29b-41d4-a716-446655440005", // candidate_profile_id
+    "770e8400-e29b-41d4-a716-446655440002", // job_description_id
+    "I am very interested in this position and believe my experience in React and Node.js makes me a great fit..."
+);
+
+// Response:
+{
+    success: true,
+    data: {
+        application_id: "dd0e8400-e29b-41d4-a716-446655440008"
+    }
+}
+
+// Error Response:
+{
+    success: false,
+    message: "Can not create job application"
+}
+```
+
+### behindAPI.easyjob.V10.applications.get(jobDescriptionId)
+Retrieves a candidate's job application for a specific job description. Returns only one record as each candidate can have only one application per job description.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to get the application for
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.applications.get(
+    "770e8400-e29b-41d4-a716-446655440002"
+);
+
+// Response (application found):
+{
+    success: true,
+    data: {
+        application_id: "dd0e8400-e29b-41d4-a716-446655440008",
+        candidate_profile_id: "aa0e8400-e29b-41d4-a716-446655440005",
+        job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+        message: "I am very interested in this position and believe my experience...",
+        status: "submitted",
+        created_at: "2024-01-15T10:30:00Z",
+        updated_at: "2024-01-15T10:30:00Z"
+    }
+}
+
+// Error Response (no application found):
+{
+    success: false,
+    message: "No application found for this job description"
+}
+```
+
+### behindAPI.easyjob.V10.applications.getQuestions(jobDescriptionId, category)
+Retrieves application questions for a specific job description filtered by category. This allows you to get custom questions that candidates need to answer when applying for specific positions.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to get questions for
+- `category` (string, required) - The category to filter questions by (e.g., "technical", "behavioral", "experience")
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.applications.getQuestions(
+    "770e8400-e29b-41d4-a716-446655440002",
+    "technical"
+);
+
+// Response:
+{
+    success: true,
+    data: [
+        {
+            id: "qq0e8400-e29b-41d4-a716-446655440001",
+            job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+            question: "Describe your experience with React and state management",
+            requirement: "Must have at least 2 years of React experience",
+            category: "technical",
+            type: "text",
+            created_at: "2024-01-15T10:30:00Z"
+        },
+        {
+            id: "qq0e8400-e29b-41d4-a716-446655440002",
+            job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+            question: "What is your preferred approach to testing React components?",
+            requirement: "Knowledge of testing frameworks required",
+            category: "technical",
+            type: "text",
+            created_at: "2024-01-15T10:35:00Z"
+        }
+    ]
+}
+
+// Error Response:
+{
+    success: false,
+    message: "Can't finish request"
+}
+```
+
+---
+
+## Data Structure Reference
+
+### Application Creation Response
+The `create()` method returns:
+
+**Success Response:**
+- `success` (boolean) - Always `true` for successful requests
+- `data` (object) - Container for response data
+    - `application_id` (UUID) - The newly created application's unique identifier
+
+**Error Response:**
+- `success` (boolean) - Always `false` for failed requests
+- `message` (string) - Error description
+
+### Application Retrieval Response
+The `get()` method returns:
+
+**Success Response:**
+- `success` (boolean) - Always `true` for successful requests
+- `data` (object) - The application record
+    - `application_id` (UUID) - Unique identifier for the application
+    - `candidate_profile_id` (UUID) - The candidate who submitted the application
+    - `job_description_id` (UUID) - The job posting this application is for
+    - `message` (string) - Application message/cover letter from the candidate
+    - `status` (string) - Current status of the application
+    - `created_at` (timestamp) - When the application was submitted
+    - `updated_at` (timestamp) - When the application was last modified
+
+**Error Response:**
+- `success` (boolean) - Always `false` for failed requests
+- `message` (string) - Error description (e.g., "No application found for this job description")
+
+### Application Questions Response
+The `getQuestions()` method returns an array of question objects:
+
+**Question Object Structure:**
+- `id` (UUID) - Unique identifier for the question
+- `job_description_id` (UUID) - The job posting this question belongs to
+- `question` (string) - The actual question text
+- `requirement` (string) - Any specific requirements or context for the question
+- `category` (string) - Question category (technical, behavioral, experience, etc.)
+- `type` (string) - Question type (text, multiple_choice, rating, etc.)
+- `created_at` (timestamp) - When the question was created
+
+---
+
+## Complete Usage Examples
+
+### Checking for Existing Applications
+
+```javascript
+// Example: Check if candidate has already applied before creating new application
+async function checkAndCreateApplication(candidateProfileId, jobDescriptionId, message) {
+    try {
+        // First, check if an application already exists
+        console.log("Checking for existing application...");
+        const existingApplication = await behindAPI.easyjob.V10.applications.get(jobDescriptionId);
+        
+        if (existingApplication.success) {
+            console.log("✓ Application already exists!");
+            console.log(`Application ID: ${existingApplication.data.application_id}`);
+            console.log(`Status: ${existingApplication.data.status}`);
+            console.log(`Submitted: ${existingApplication.data.created_at}`);
+            
+            return {
+                success: true,
+                status: 'existing',
+                applicationId: existingApplication.data.application_id,
+                data: existingApplication.data
+            };
+        } else {
+            // No existing application found, create a new one
+            console.log("No existing application found. Creating new application...");
+            const newApplication = await behindAPI.easyjob.V10.applications.create(
+                candidateProfileId,
+                jobDescriptionId,
+                message
+            );
+            
+            if (newApplication.success) {
+                console.log("✓ New application created successfully!");
+                console.log(`Application ID: ${newApplication.data.application_id}`);
+                
+                return {
+                    success: true,
+                    status: 'created',
+                    applicationId: newApplication.data.application_id
+                };
+            } else {
+                console.log(`✗ Failed to create application: ${newApplication.message}`);
+                return {
+                    success: false,
+                    error: newApplication.message
+                };
+            }
+        }
+    } catch (error) {
+        console.error("Error in application workflow:", error);
+        return {
+            success: false,
+            error: error.message
+        };
+    }
+}
+
+// Usage
+const result = await checkAndCreateApplication(
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    "770e8400-e29b-41d4-a716-446655440002",
+    "I am very interested in this position..."
+);
+
+console.log("Application Result:", result);
+```
+
+### Creating Job Applications
+
+```javascript
+// Example: Candidate applying for multiple positions
+async function applyToMultipleJobs(candidateProfileId, jobIds, applicationMessage) {
+    const results = [];
+    
+    for (const jobId of jobIds) {
+        try {
+            const application = await behindAPI.easyjob.V10.applications.create(
+                candidateProfileId,
+                jobId,
+                applicationMessage
+            );
+            
+            if (application.success) {
+                console.log(`✓ Successfully applied to job ${jobId}`);
+                console.log(`  Application ID: ${application.data.application_id}`);
+                results.push({
+                    jobId,
+                    applicationId: application.data.application_id,
+                    status: 'success'
+                });
+            } else {
+                console.log(`✗ Failed to apply to job ${jobId}: ${application.message}`);
+                results.push({
+                    jobId,
+                    status: 'failed',
+                    error: application.message
+                });
+            }
+        } catch (error) {
+            console.error(`Error applying to job ${jobId}:`, error);
+            results.push({
+                jobId,
+                status: 'error',
+                error: error.message
+            });
+        }
+    }
+    
+    return results;
+}
+
+// Usage
+const candidateId = "aa0e8400-e29b-41d4-a716-446655440005";
+const jobIds = [
+    "770e8400-e29b-41d4-a716-446655440002",
+    "880e8400-e29b-41d4-a716-446655440003",
+    "990e8400-e29b-41d4-a716-446655440004"
+];
+const message = "I am excited to contribute my skills to your team...";
+
+const applicationResults = await applyToMultipleJobs(candidateId, jobIds, message);
+console.log("Application Summary:", applicationResults);
+```
+
+### Application Status Dashboard
+
+```javascript
+// Example: Build a dashboard showing application status across multiple jobs
+async function buildApplicationDashboard(jobDescriptionIds) {
+    const dashboard = {
+        applications: [],
+        summary: {
+            total: 0,
+            applied: 0,
+            notApplied: 0
+        }
+    };
+    
+    for (const jobId of jobDescriptionIds) {
+        try {
+            const application = await behindAPI.easyjob.V10.applications.get(jobId);
+            
+            if (application.success) {
+                // Application exists
+                dashboard.applications.push({
+                    jobId,
+                    status: 'applied',
+                    applicationId: application.data.application_id,
+                    submittedAt: application.data.created_at,
+                    currentStatus: application.data.status,
+                    message: application.data.message
+                });
+                dashboard.summary.applied++;
+            } else {
+                // No application found
+                dashboard.applications.push({
+                    jobId,
+                    status: 'not_applied',
+                    applicationId: null,
+                    submittedAt: null,
+                    currentStatus: null,
+                    message: null
+                });
+                dashboard.summary.notApplied++;
+            }
+            dashboard.summary.total++;
+        } catch (error) {
+            console.error(`Error checking application for job ${jobId}:`, error);
+            dashboard.applications.push({
+                jobId,
+                status: 'error',
+                error: error.message
+            });
+        }
+    }
+    
+    return dashboard;
+}
+
+// Usage
+const jobIds = [
+    "770e8400-e29b-41d4-a716-446655440002",
+    "880e8400-e29b-41d4-a716-446655440003",
+    "990e8400-e29b-41d4-a716-446655440004"
+];
+
+const dashboard = await buildApplicationDashboard(jobIds);
+
+console.log("=== APPLICATION DASHBOARD ===");
+console.log(`Total Jobs: ${dashboard.summary.total}`);
+console.log(`Applied: ${dashboard.summary.applied}`);
+console.log(`Not Applied: ${dashboard.summary.notApplied}`);
+
+console.log("\n=== DETAILED STATUS ===");
+dashboard.applications.forEach((app, index) => {
+    console.log(`${index + 1}. Job ${app.jobId}`);
+    console.log(`   Status: ${app.status.toUpperCase()}`);
+    if (app.status === 'applied') {
+        console.log(`   Application ID: ${app.applicationId}`);
+        console.log(`   Submitted: ${app.submittedAt}`);
+        console.log(`   Current Status: ${app.currentStatus}`);
+    }
+    console.log('');
+});
+```
+
+### Retrieving and Processing Application Questions
+
+```javascript
+// Example: Get all questions for a job posting across different categories
+async function getAllJobQuestions(jobDescriptionId) {
+    const categories = ['technical', 'behavioral', 'experience', 'general'];
+    const allQuestions = {};
+    
+    for (const category of categories) {
+        try {
+            const questions = await behindAPI.easyjob.V10.applications.getQuestions(
+                jobDescriptionId,
+                category
+            );
+            
+            if (questions.success && questions.data.length > 0) {
+                allQuestions[category] = questions.data;
+                console.log(`Found ${questions.data.length} ${category} questions`);
+            } else {
+                console.log(`No ${category} questions found`);
+                allQuestions[category] = [];
+            }
+        } catch (error) {
+            console.error(`Error retrieving ${category} questions:`, error);
+            allQuestions[category] = [];
+        }
+    }
+    
+    return allQuestions;
+}
+
+// Usage
+const jobId = "770e8400-e29b-41d4-a716-446655440002";
+const questionsByCategory = await getAllJobQuestions(jobId);
+
+// Display questions in a structured format
+Object.entries(questionsByCategory).forEach(([category, questions]) => {
+    if (questions.length > 0) {
+        console.log(`\n=== ${category.toUpperCase()} QUESTIONS ===`);
+        questions.forEach((q, index) => {
+            console.log(`${index + 1}. ${q.question}`);
+            if (q.requirement) {
+                console.log(`   Requirement: ${q.requirement}`);
+            }
+            console.log(`   Type: ${q.type}`);
+            console.log('');
+        });
+    }
+});
+```
+
+### Building an Application Form Interface
+
+```javascript
+// Example: Create a dynamic application form based on job questions
+async function buildApplicationForm(jobDescriptionId) {
+    try {
+        // Get questions for different categories
+        const categories = ['general', 'technical', 'behavioral'];
+        const formSections = {};
+        
+        for (const category of categories) {
+            const result = await behindAPI.easyjob.V10.applications.getQuestions(
+                jobDescriptionId,
+                category
+            );
+            
+            if (result.success && result.data.length > 0) {
+                formSections[category] = result.data.map(question => ({
+                    id: question.id,
+                    label: question.question,
+                    type: question.type,
+                    required: question.requirement ? true : false,
+                    helpText: question.requirement,
+                    category: question.category
+                }));
+            }
+        }
+        
+        // Generate form structure
+        const applicationForm = {
+            jobDescriptionId: jobDescriptionId,
+            sections: formSections,
+            metadata: {
+                totalQuestions: Object.values(formSections).flat().length,
+                categories: Object.keys(formSections),
+                createdAt: new Date().toISOString()
+            }
+        };
+        
+        console.log("=== APPLICATION FORM STRUCTURE ===");
+        console.log(`Job ID: ${jobDescriptionId}`);
+        console.log(`Total Questions: ${applicationForm.metadata.totalQuestions}`);
+        console.log(`Categories: ${applicationForm.metadata.categories.join(', ')}`);
+        
+        // Display form sections
+        Object.entries(formSections).forEach(([category, questions]) => {
+            console.log(`\n--- ${category.toUpperCase()} SECTION (${questions.length} questions) ---`);
+            questions.forEach((field, index) => {
+                console.log(`${index + 1}. ${field.label}${field.required ? ' *' : ''}`);
+                console.log(`   Type: ${field.type}`);
+                if (field.helpText) {
+                    console.log(`   Help: ${field.helpText}`);
+                }
+            });
+        });
+        
+        return applicationForm;
+        
+    } catch (error) {
+        console.error("Error building application form:", error);
+        return null;
+    }
+}
+
+// Usage
+const formStructure = await buildApplicationForm("770e8400-e29b-41d4-a716-446655440002");
+```
+
+### Complete Application Workflow
+
+```javascript
+// Example: Complete workflow from questions to application submission
+async function completeApplicationWorkflow(candidateProfileId, jobDescriptionId) {
+    try {
+        console.log("=== STARTING APPLICATION WORKFLOW ===");
+        
+        // Step 1: Check for existing application
+        console.log("\n1. Checking for existing application...");
+        const existingApp = await behindAPI.easyjob.V10.applications.get(jobDescriptionId);
+        
+        if (existingApp.success) {
+            console.log("   ⚠️ Application already exists!");
+            console.log(`   Application ID: ${existingApp.data.application_id}`);
+            console.log(`   Status: ${existingApp.data.status}`);
+            console.log(`   Submitted: ${existingApp.data.created_at}`);
+            
+            return {
+                success: true,
+                status: 'existing',
+                applicationId: existingApp.data.application_id,
+                data: existingApp.data
+            };
+        }
+        
+        // Step 2: Retrieve all application questions
+        console.log("\n2. Retrieving application questions...");
+        const categories = ['general', 'technical', 'behavioral', 'experience'];
+        const allQuestions = [];
+        
+        for (const category of categories) {
+            const questions = await behindAPI.easyjob.V10.applications.getQuestions(
+                jobDescriptionId,
+                category
+            );
+            
+            if (questions.success) {
+                allQuestions.push(...questions.data);
+                console.log(`   ✓ Retrieved ${questions.data.length} ${category} questions`);
+            }
+        }
+        
+        console.log(`   Total questions to answer: ${allQuestions.length}`);
+        
+        // Step 3: Simulate candidate answers (in real app, this would be user input)
+        console.log("\n3. Processing candidate responses...");
+        const candidateResponses = allQuestions.map(question => ({
+            questionId: question.id,
+            question: question.question,
+            category: question.category,
+            response: generateSampleResponse(question)
+        }));
+        
+        // Step 4: Prepare application message
+        const applicationMessage = `
+Dear Hiring Manager,
+
+I am excited to apply for this position. Based on the application questions, I believe I am well-qualified for this role.
+
+${candidateResponses.map(r => 
+    `${r.question}\n${r.response}\n`
+).join('\n')}
+
+I look forward to discussing my qualifications further.
+
+Best regards,
+[Candidate Name]
+        `.trim();
+        
+        // Step 5: Submit application
+        console.log("\n4. Submitting application...");
+        const applicationResult = await behindAPI.easyjob.V10.applications.create(
+            candidateProfileId,
+            jobDescriptionId,
+            applicationMessage
+        );
+        
+        if (applicationResult.success) {
+            console.log("   ✓ Application submitted successfully!");
+            console.log(`   Application ID: ${applicationResult.data.application_id}`);
+            
+            return {
+                success: true,
+                status: 'created',
+                applicationId: applicationResult.data.application_id,
+                questionsAnswered: allQuestions.length,
+                responses: candidateResponses
+            };
+        } else {
+            console.log(`   ✗ Application failed: ${applicationResult.message}`);
+            return {
+                success: false,
+                error: applicationResult.message
+            };
+        }
+        
+    } catch (error) {
+        console.error("Error in application workflow:", error);
+        return {
+            success: false,
+            error: error.message
+        };
+    }
+}
+
+// Helper function to generate sample responses (replace with actual user input)
+function generateSampleResponse(question) {
+    const sampleResponses = {
+        'technical': 'I have extensive experience with the mentioned technologies and have successfully implemented similar solutions in my previous roles.',
+        'behavioral': 'I approach challenges systematically by analyzing the situation, identifying key stakeholders, and developing collaborative solutions.',
+        'experience': 'In my previous role, I gained valuable experience that directly relates to this position and the requirements outlined.',
+        'general': 'I am passionate about this opportunity and believe my skills and enthusiasm make me an ideal candidate.'
+    };
+    
+    return sampleResponses[question.category] || 'I am confident in my ability to handle this aspect of the role effectively.';
+}
+
+// Usage
+const result = await completeApplicationWorkflow(
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    "770e8400-e29b-41d4-a716-446655440002"
+);
+
+console.log("\n=== WORKFLOW RESULT ===");
+console.log(result);
+```
+
+---
+
+## Best Practices
+
+1. **Application Checking**: Always check for existing applications before creating new ones to avoid duplicates and provide better user experience.
+
+2. **Question Categories**: Use consistent category naming (technical, behavioral, experience, general) to organize questions logically and make them easier to retrieve and display.
+
+3. **Error Handling**: Always check the `success` property before processing data. Handle both API errors and network failures gracefully.
+
+4. **Message Formatting**: When creating applications with messages, consider formatting them clearly with proper structure, especially if incorporating answers to application questions.
+
+5. **Data Validation**: Validate UUIDs before making API calls to avoid unnecessary requests and improve error handling.
+
+6. **User Experience**: Retrieve questions first to build dynamic forms, allowing candidates to see all requirements before starting their application.
+
+7. **Performance**: Cache questions for frequently accessed job postings to reduce API calls and improve response times.
+
+8. **Status Management**: Use the `get` method to build dashboards and track application status across multiple job postings.
+
+---
+
+## Error Handling
+
+All methods return a response object with a `success` boolean property. When `success` is `false`, a `message` property contains the error description.
+
+```javascript
+// Comprehensive error handling example
+async function safeApplicationOperations(candidateProfileId, jobDescriptionId, message) {
+    try {
+        // Validate input parameters
+        if (!candidateProfileId || !jobDescriptionId) {
+            return {
+                success: false,
+                error: "Missing required parameters"
+            };
+        }
+        
+        // Validate UUID format (basic check)
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+        if (!uuidRegex.test(candidateProfileId) || !uuidRegex.test(jobDescriptionId)) {
+            return {
+                success: false,
+                error: "Invalid UUID format"
+            };
+        }
+        
+        // Check for existing application first
+        const existingApp = await behindAPI.easyjob.V10.applications.get(jobDescriptionId);
+        
+        if (existingApp.success) {
+            return {
+                success: true,
+                status: 'existing',
+                applicationId: existingApp.data.application_id,
+                data: existingApp.data
+            };
+        }
+        
+        // Create new application
+        const newApp = await behindAPI.easyjob.V10.applications.create(
+            candidateProfileId,
+            jobDescriptionId,
+            message
+        );
+        
+        if (!newApp.success) {
+            console.error("API Error:", newApp.message);
+            return {
+                success: false,
+                error: newApp.message
+            };
+        }
+        
+        return {
+            success: true,
+            status: 'created',
+            applicationId: newApp.data.application_id
+        };
+        
+    } catch (error) {
+        console.error("Unexpected error:", error);
+        return {
+            success: false,
+            error: "An unexpected error occurred"
+        };
+    }
+}
+
+// Usage with comprehensive error handling
+const result = await safeApplicationOperations(
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    "770e8400-e29b-41d4-a716-446655440002",
+    "Application message here"
+);
+
+if (result.success) {
+    if (result.status === 'existing') {
+        console.log("Application already exists:", result.applicationId);
+    } else {
+        console.log("New application created:", result.applicationId);
+    }
+} else {
+    console.error("Operation failed:", result.error);
+    // Handle error appropriately (show user message, retry, etc.)
+}
+```
+
+---
+
+## Integration Notes
+
+The Applications API works seamlessly with other EasyJob APIs:
+
+- **Job Descriptions**: Applications are created for specific job postings retrieved via the Job Descriptions API
+- **Candidate Profiles**: Applications link candidates to jobs, with profile data accessible through other API endpoints
+- **Applicants API**: Once created, applications can be managed through the Applicants API for stage tracking and detailed retrieval
+- **Questions Management**: Custom questions are defined per job description and retrieved to build dynamic application forms
+
+---
+
+## Authorization Requirements
+
+All API methods require user authorization:
+- `create`: Requires valid user session (`need_authorization: true`)
+- `get`: Requires valid user session (`need_authorization: true`)
+- `getQuestions`: Requires valid user session (`need_authorization: true`)
+
+Ensure your API client is properly authenticated before making requests to these endpoints.