node-behind-api-client 2.0.48

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

@@ -0,0 +1,654 @@
+# Job Descriptions API Extension
+
+This document extends the main EasyJob JavaScript API Client Documentation with detailed information about the Job Descriptions API methods.
+
+## Overview
+
+The Job Descriptions API allows you to manage job postings throughout their lifecycle. This includes creating, updating, publishing, and managing job descriptions, as well as controlling their status and visibility to potential candidates.
+
+---
+
+## Job Descriptions API
+
+### behindAPI.easyjob.V10.jobDescriptions.create(departmentId, title, description)
+Creates a new job description record within a specified department.
+
+**Parameters:**
+- `departmentId` (string, required) - The department UUID where the job description belongs
+- `title` (string, required) - The title of the job description
+- `description` (string, optional) - The detailed description text of the job
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.create(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "Senior Software Engineer",
+    "We are looking for an experienced software engineer to join our team..."
+);
+
+// Response:
+{
+    success: true,
+    data: {
+        job_description_id: "770e8400-e29b-41d4-a716-446655440002"
+    }
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.get(jobDescriptionId)
+Retrieves detailed information for a specific job description.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to retrieve
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.get("770e8400-e29b-41d4-a716-446655440002");
+
+// Response:
+{
+    success: true,
+    data: {
+        job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+        department_id: "550e8400-e29b-41d4-a716-446655440001",
+        title: "Senior Software Engineer",
+        description: "We are looking for an experienced software engineer...",
+        status: "draft",
+        published: false,
+        published_at: null,
+        deadline_at: null,
+        closed: false,
+        closed_at: null,
+        deleted: false,
+        created_at: "2024-01-15T10:30:00Z",
+        updated_at: "2024-01-15T10:30:00Z",
+        created_by: "user123",
+        data: {}
+    }
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.getList(departmentId)
+Retrieves a list of all job descriptions for a specific department.
+
+**Parameters:**
+- `departmentId` (string, required) - The department UUID to get job descriptions for
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.getList("550e8400-e29b-41d4-a716-446655440001");
+
+// Response:
+{
+    success: true,
+    data: [
+        {
+            job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+            department_id: "550e8400-e29b-41d4-a716-446655440001",
+            title: "Senior Software Engineer",
+            description: "We are looking for an experienced software engineer...",
+            status: "published",
+            published: true,
+            published_at: "2024-01-20T09:00:00Z",
+            deadline_at: "2024-02-20T23:59:59Z",
+            closed: false,
+            created_at: "2024-01-15T10:30:00Z",
+            updated_at: "2024-01-20T09:00:00Z"
+        },
+        {
+            job_description_id: "880e8400-e29b-41d4-a716-446655440003",
+            department_id: "550e8400-e29b-41d4-a716-446655440001",
+            title: "Frontend Developer",
+            description: "Join our frontend team to build amazing user experiences...",
+            status: "draft",
+            published: false,
+            published_at: null,
+            deadline_at: null,
+            closed: false,
+            created_at: "2024-01-18T14:15:00Z",
+            updated_at: "2024-01-18T14:15:00Z"
+        }
+    ]
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.getUnauthorised(jobDescriptionId)
+Retrieves a specific job description without requiring authorization - used for public job listings.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to retrieve
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.getUnauthorised("770e8400-e29b-41d4-a716-446655440002");
+
+// Response:
+{
+    success: true,
+    data: {
+        job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+        title: "Senior Software Engineer",
+        description: "We are looking for an experienced software engineer...",
+        published_at: "2024-01-20T09:00:00Z",
+        deadline_at: "2024-02-20T23:59:59Z",
+        department_name: "Engineering"
+    }
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.update(jobDescriptionId, title, description, publishedAt, deadlineAt)
+Updates an existing job description with optional parameters.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to update
+- `title` (string, optional) - The new job title
+- `description` (string, optional) - The new job description text
+- `publishedAt` (string, optional) - ISO 8601 timestamp for publication date
+- `deadlineAt` (string, optional) - ISO 8601 timestamp for application deadline
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.update(
+    "770e8400-e29b-41d4-a716-446655440002",
+    "Senior Full-Stack Engineer",
+    "Updated job description with new requirements...",
+    "2024-01-25T09:00:00Z",
+    "2024-03-01T23:59:59Z"
+);
+
+// Response:
+{
+    success: true
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.updateData(jobDescriptionId, data)
+Updates the custom data object associated with a job description.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to update
+- `data` (object, required) - Custom data object to store with the job description
+
+**Usage:**
+```javascript
+const customData = {
+    requirements: {
+        experience_years: 5,
+        required_skills: ["JavaScript", "React", "Node.js"],
+        preferred_skills: ["AWS", "Docker", "Kubernetes"]
+    },
+    benefits: ["Health Insurance", "401k", "Remote Work"],
+    salary_range: {
+        min: 90000,
+        max: 130000,
+        currency: "USD"
+    }
+};
+
+const result = await behindAPI.easyjob.V10.jobDescriptions.updateData(
+    "770e8400-e29b-41d4-a716-446655440002",
+    customData
+);
+
+// Response:
+{
+    success: true
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.textUpdate(jobDescriptionId, text)
+Updates the text content of a job description.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to update
+- `text` (string, required) - The new text content
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.textUpdate(
+    "770e8400-e29b-41d4-a716-446655440002",
+    "Updated job description with comprehensive details about the role..."
+);
+
+// Response:
+{
+    success: true
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.publish(jobDescriptionId)
+Publishes a job description, making it visible to potential candidates.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to publish
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.publish("770e8400-e29b-41d4-a716-446655440002");
+
+// Response:
+{
+    success: true
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.close(jobDescriptionId)
+Closes a job description, preventing new applications while preserving existing data.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to close
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.close("770e8400-e29b-41d4-a716-446655440002");
+
+// Response:
+{
+    success: true
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.updateStatus(jobDescriptionId, status)
+Updates the status of a job description with user permission validation.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to update
+- `status` (string, required) - The new status value
+
+**Common Status Values:**
+- `"draft"` - Job is in draft state
+- `"published"` - Job is published and visible
+- `"closed"` - Job is closed to new applications
+- `"on_hold"` - Job posting is temporarily paused
+- `"cancelled"` - Job posting has been cancelled
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.updateStatus(
+    "770e8400-e29b-41d4-a716-446655440002",
+    "on_hold"
+);
+
+// Response:
+{
+    success: true
+}
+```
+
+### behindAPI.easyjob.V10.jobDescriptions.delete(jobDescriptionId)
+Soft deletes a job description (sets deleted flag to true).
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to delete
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.jobDescriptions.delete("770e8400-e29b-41d4-a716-446655440002");
+
+// Response:
+{
+    success: true
+}
+```
+
+---
+
+## Data Structure Reference
+
+### Job Description Object
+The complete job description object includes:
+
+**Core Fields:**
+- `job_description_id` (UUID) - Unique identifier for the job description
+- `department_id` (UUID) - The department this job belongs to
+- `title` (string) - Job title
+- `description` (string) - Detailed job description text
+- `status` (string) - Current status (draft, published, closed, etc.)
+- `data` (object) - Custom data object for additional information
+
+**Publication Fields:**
+- `published` (boolean) - Whether the job is published
+- `published_at` (timestamp) - When the job was published
+- `deadline_at` (timestamp) - Application deadline
+
+**State Management:**
+- `closed` (boolean) - Whether the job is closed
+- `closed_at` (timestamp) - When the job was closed
+- `deleted` (boolean) - Whether the job is deleted
+
+**Audit Fields:**
+- `created_at` (timestamp) - Creation timestamp
+- `updated_at` (timestamp) - Last update timestamp
+- `created_by` (string) - User who created the job
+
+---
+
+## Complete Usage Example
+
+```javascript
+// Complete workflow for managing job descriptions
+async function manageJobDescriptions(departmentId) {
+    try {
+        // 1. Create a new job description
+        const newJob = await behindAPI.easyjob.V10.jobDescriptions.create(
+            departmentId,
+            "Senior DevOps Engineer",
+            "We are seeking a experienced DevOps engineer to join our infrastructure team..."
+        );
+
+        if (!newJob.success) {
+            console.error("Failed to create job description");
+            return;
+        }
+
+        const jobId = newJob.data.job_description_id;
+        console.log(`Created job description: ${jobId}`);
+
+        // 2. Add custom data with requirements and benefits
+        const jobData = {
+            requirements: {
+                experience_years: 5,
+                required_skills: ["Docker", "Kubernetes", "AWS", "Terraform"],
+                certifications: ["AWS Certified DevOps Engineer"]
+            },
+            benefits: [
+                "Competitive salary",
+                "Health, dental, and vision insurance",
+                "401(k) with company match",
+                "Flexible work arrangements",
+                "Professional development budget"
+            ],
+            salary_range: {
+                min: 100000,
+                max: 140000,
+                currency: "USD"
+            },
+            location: {
+                type: "hybrid",
+                office_location: "San Francisco, CA",
+                remote_percentage: 50
+            }
+        };
+
+        const dataUpdate = await behindAPI.easyjob.V10.jobDescriptions.updateData(jobId, jobData);
+        if (dataUpdate.success) {
+            console.log("Added custom job data");
+        }
+
+        // 3. Update the job description with more details
+        const detailedDescription = `
+# Senior DevOps Engineer
+
+## About the Role
+Join our growing infrastructure team to build and maintain scalable, reliable systems that power our applications.
+
+## Key Responsibilities
+- Design and implement CI/CD pipelines
+- Manage cloud infrastructure on AWS
+- Monitor system performance and reliability
+- Collaborate with development teams on deployment strategies
+- Implement security best practices
+
+## Requirements
+- 5+ years of DevOps experience
+- Strong experience with containerization (Docker, Kubernetes)
+- Proficiency with Infrastructure as Code (Terraform, CloudFormation)
+- Experience with monitoring tools (Prometheus, Grafana, ELK stack)
+- Strong scripting skills (Python, Bash)
+
+## Nice to Have
+- AWS certification
+- Experience with service mesh technologies
+- Knowledge of GitOps practices
+        `;
+
+        const updateResult = await behindAPI.easyjob.V10.jobDescriptions.update(
+            jobId,
+            "Senior DevOps Engineer",
+            detailedDescription,
+            null, // published_at - will be set when published
+            "2024-03-15T23:59:59Z" // deadline_at
+        );
+
+        if (updateResult.success) {
+            console.log("Updated job description details");
+        }
+
+        // 4. Publish the job description
+        const publishResult = await behindAPI.easyjob.V10.jobDescriptions.publish(jobId);
+        if (publishResult.success) {
+            console.log("Job description published successfully");
+        }
+
+        // 5. Get the updated job description
+        const finalJob = await behindAPI.easyjob.V10.jobDescriptions.get(jobId);
+        if (finalJob.success) {
+            console.log("Final job description:", finalJob.data);
+        }
+
+        return jobId;
+
+    } catch (error) {
+        console.error("Error managing job descriptions:", error);
+    }
+}
+
+// Example: Bulk operations on job descriptions
+async function bulkManageJobs(departmentId) {
+    try {
+        // Get all job descriptions for the department
+        const jobsList = await behindAPI.easyjob.V10.jobDescriptions.getList(departmentId);
+
+        if (!jobsList.success) {
+            console.error("Failed to retrieve jobs list");
+            return;
+        }
+
+        console.log(`Found ${jobsList.data.length} job descriptions`);
+
+        // Process each job description
+        for (const job of jobsList.data) {
+            console.log(`\nProcessing job: ${job.title}`);
+            console.log(`Status: ${job.status}`);
+            console.log(`Published: ${job.published}`);
+
+            // Close jobs that have passed their deadline
+            if (job.deadline_at && new Date(job.deadline_at) < new Date() && !job.closed) {
+                const closeResult = await behindAPI.easyjob.V10.jobDescriptions.close(job.job_description_id);
+                if (closeResult.success) {
+                    console.log(`  → Closed expired job: ${job.title}`);
+                }
+            }
+
+            // Publish draft jobs that are ready
+            if (job.status === "draft" && job.description && job.description.length > 100) {
+                const publishResult = await behindAPI.easyjob.V10.jobDescriptions.publish(job.job_description_id);
+                if (publishResult.success) {
+                    console.log(`  → Published job: ${job.title}`);
+                }
+            }
+        }
+
+        // Generate summary report
+        const summary = {
+            total: jobsList.data.length,
+            published: jobsList.data.filter(job => job.published).length,
+            draft: jobsList.data.filter(job => !job.published && !job.closed).length,
+            closed: jobsList.data.filter(job => job.closed).length,
+            expired: jobsList.data.filter(job => 
+                job.deadline_at && new Date(job.deadline_at) < new Date()
+            ).length
+        };
+
+        console.log("\n=== Department Job Summary ===");
+        console.log(`Total Jobs: ${summary.total}`);
+        console.log(`Published: ${summary.published}`);
+        console.log(`Draft: ${summary.draft}`);
+        console.log(`Closed: ${summary.closed}`);
+        console.log(`Expired: ${summary.expired}`);
+
+        return summary;
+
+    } catch (error) {
+        console.error("Error in bulk job management:", error);
+    }
+}
+
+// Example: Job template system
+async function createJobFromTemplate(departmentId, templateName, customizations = {}) {
+    const templates = {
+        "software_engineer": {
+            title: "Software Engineer",
+            description: "Join our engineering team to build innovative software solutions...",
+            data: {
+                requirements: {
+                    experience_years: 3,
+                    required_skills: ["JavaScript", "React", "Node.js"],
+                    education: "Bachelor's degree in Computer Science or related field"
+                },
+                benefits: ["Health Insurance", "401k", "Flexible Hours"]
+            }
+        },
+        "product_manager": {
+            title: "Product Manager",
+            description: "Lead product development from conception to launch...",
+            data: {
+                requirements: {
+                    experience_years: 5,
+                    required_skills: ["Product Strategy", "Data Analysis", "User Research"],
+                    education: "Bachelor's degree in Business, Engineering, or related field"
+                },
+                benefits: ["Health Insurance", "401k", "Stock Options"]
+            }
+        },
+        "designer": {
+            title: "UX/UI Designer",
+            description: "Create beautiful and intuitive user experiences...",
+            data: {
+                requirements: {
+                    experience_years: 3,
+                    required_skills: ["Figma", "Adobe Creative Suite", "User Research"],
+                    portfolio: "Required"
+                },
+                benefits: ["Health Insurance", "401k", "Creative Budget"]
+            }
+        }
+    };
+
+    const template = templates[templateName];
+    if (!template) {
+        throw new Error(`Template "${templateName}" not found`);
+    }
+
+    try {
+        // Create job from template
+        const job = await behindAPI.easyjob.V10.jobDescriptions.create(
+            departmentId,
+            customizations.title || template.title,
+            customizations.description || template.description
+        );
+
+        if (!job.success) {
+            throw new Error("Failed to create job from template");
+        }
+
+        const jobId = job.data.job_description_id;
+
+        // Apply template data with customizations
+        const finalData = {
+            ...template.data,
+            ...customizations.data
+        };
+
+        await behindAPI.easyjob.V10.jobDescriptions.updateData(jobId, finalData);
+
+        // Set deadline if provided
+        if (customizations.deadline_at) {
+            await behindAPI.easyjob.V10.jobDescriptions.update(
+                jobId,
+                null, null, null,
+                customizations.deadline_at
+            );
+        }
+
+        console.log(`Created job from template "${templateName}": ${jobId}`);
+        return jobId;
+
+    } catch (error) {
+        console.error("Error creating job from template:", error);
+        throw error;
+    }
+}
+
+// Usage examples:
+// Create a senior-level software engineer position
+const seniorEngJobId = await createJobFromTemplate(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "software_engineer",
+    {
+        title: "Senior Software Engineer",
+        data: {
+            requirements: {
+                experience_years: 7,
+                required_skills: ["JavaScript", "React", "Node.js", "AWS", "Docker"],
+                leadership: "Experience mentoring junior developers"
+            },
+            salary_range: {
+                min: 120000,
+                max: 160000,
+                currency: "USD"
+            }
+        },
+        deadline_at: "2024-04-01T23:59:59Z"
+    }
+);
+```
+
+---
+
+## Best Practices
+
+1. **Lifecycle Management**: Use a consistent workflow: create → update → publish → manage → close. Always validate job descriptions before publishing.
+
+2. **Data Organization**: Use the `updateData()` method to store structured information like requirements, benefits, and salary ranges for better searchability and filtering.
+
+3. **Publishing Strategy**: Review job descriptions thoroughly before publishing. Once published, jobs become visible to candidates.
+
+4. **Deadline Management**: Always set realistic application deadlines and monitor for expired jobs that need to be closed.
+
+5. **Template Usage**: Create reusable job templates for common positions to ensure consistency and save time.
+
+6. **Status Tracking**: Implement automated workflows to track job status and lifecycle events.
+
+---
+
+## Error Handling
+
+All methods return a response object with a `success` boolean property. When `success` is `false`, a `message` property will contain the error description.
+
+```javascript
+// Example error handling
+const result = await behindAPI.easyjob.V10.jobDescriptions.get(invalidJobId);
+
+if (!result.success) {
+    console.error("Error retrieving job description:", result.message);
+    // Handle the error appropriately
+    return;
+}
+
+// Process successful result
+const jobData = result.data;
+```
+
+---
+
+## Integration Notes
+
+The Job Descriptions API works seamlessly with other EasyJob APIs:
+
+- **Departments**: Job descriptions belong to departments and inherit permissions
+- **Applicants**: Applications are linked to specific job descriptions
+- **Job Description Candidate Questions**: Custom questions can be attached to job descriptions
+- **Candidate Profiles**: Applicant profiles can be filtered based on job requirements stored in the data field
+
+The API supports both authorized operations (for internal management) and unauthorized access (for public job listings), enabling flexible integration with career pages and job boards.