@sharpapi/sharpapi-node-job-description 1.0.0

package/README.md

@@ -0,0 +1,329 @@
+![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Node.js Client")
+
+# Job Description Generator API for Node.js
+
+## 📋 Generate professional job descriptions with AI — powered by SharpAPI.
+
+[![npm version](https://img.shields.io/npm/v/@sharpapi/sharpapi-node-job-description.svg)](https://www.npmjs.com/package/@sharpapi/sharpapi-node-job-description)
+[![License](https://img.shields.io/npm/l/@sharpapi/sharpapi-node-job-description.svg)](https://github.com/sharpapi/sharpapi-node-client/blob/master/LICENSE.md)
+
+**SharpAPI Job Description Generator** creates comprehensive, professional job descriptions based on position details, requirements, and company information. Perfect for HR departments, recruitment agencies, and job boards.
+
+---
+
+## 📋 Table of Contents
+
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+3. [Usage](#usage)
+4. [API Documentation](#api-documentation)
+5. [Response Format](#response-format)
+6. [Examples](#examples)
+7. [License](#license)
+
+---
+
+## Requirements
+
+- Node.js >= 16.x
+- npm or yarn
+
+---
+
+## Installation
+
+### Step 1. Install the package via npm:
+
+```bash
+npm install @sharpapi/sharpapi-node-job-description
+```
+
+### Step 2. Get your API key
+
+Visit [SharpAPI.com](https://sharpapi.com/) to get your API key.
+
+---
+
+## Usage
+
+```javascript
+const { SharpApiJobDescriptionService, JobDescriptionParameters } = require('@sharpapi/sharpapi-node-job-description');
+
+const apiKey = process.env.SHARP_API_KEY;
+const service = new SharpApiJobDescriptionService(apiKey);
+
+const params = new JobDescriptionParameters(
+  'Senior Software Engineer',        // name
+  'Tech Innovators Inc',             // company_name
+  '5+ years',                        // minimum_work_experience
+  "Bachelor's Degree",               // minimum_education
+  'Full-time',                       // employment_type
+  ['JavaScript', 'Node.js', 'React'], // required_skills
+  ['TypeScript', 'Docker'],          // optional_skills
+  'United States',                   // country
+  true,                              // remote
+  false,                             // visa_sponsored
+  'Professional',                    // voice_tone
+  null,                              // context
+  'English'                          // language
+);
+
+async function generateJobDescription() {
+  try {
+    const statusUrl = await service.generateJobDescription(params);
+    console.log('Job submitted. Status URL:', statusUrl);
+
+    const result = await service.fetchResults(statusUrl);
+    console.log('Job description:', result.getResultJson());
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+generateJobDescription();
+```
+
+---
+
+## API Documentation
+
+### Methods
+
+#### `generateJobDescription(params: JobDescriptionParameters): Promise<string>`
+
+Generates a comprehensive job description based on the provided parameters.
+
+**Parameters (JobDescriptionParameters):**
+- `name` (string, required): Job position name
+- `company_name` (string, optional): Company name
+- `minimum_work_experience` (string, optional): Required experience (e.g., "3-5 years")
+- `minimum_education` (string, optional): Required education level
+- `employment_type` (string, optional): Full-time, part-time, contract, etc.
+- `required_skills` (array, optional): List of required skills
+- `optional_skills` (array, optional): List of nice-to-have skills
+- `country` (string, optional): Job location country
+- `remote` (boolean, optional): Whether remote work is allowed
+- `visa_sponsored` (boolean, optional): Whether visa sponsorship is available
+- `voice_tone` (string, optional): Tone of the description (e.g., 'Professional', 'Casual')
+- `context` (string, optional): Additional custom requirements
+- `language` (string, optional): Output language (default: 'English')
+
+**Returns:**
+- Promise<string>: Status URL for polling the job result
+
+---
+
+## Response Format
+
+The API returns a structured job description with three main sections:
+
+```json
+{
+  "data": {
+    "type": "api_job_result",
+    "id": "3c4e887a-0dfd-49b6-8edb-9280e468c210",
+    "attributes": {
+      "status": "success",
+      "type": "hr_job_description",
+      "result": {
+        "job_position": "Senior PHP Software Engineer",
+        "company_name": "Apple Inc",
+        "job_short_description": "We are seeking an experienced Senior PHP Software Engineer to join our dynamic team at Apple Inc. This is a full-time, remote position based in the United Kingdom with visa sponsorship available for qualified candidates.",
+        "job_requirements": [
+          "Bachelor's Degree in Computer Science or related field",
+          "Minimum 5 years of professional PHP development experience",
+          "Expert knowledge of PHP8 and modern PHP practices",
+          "Strong experience with Laravel framework",
+          "Proficiency in MySQL database design and optimization",
+          "Valid C-class driving license",
+          "Excellent problem-solving and analytical skills",
+          "Strong communication skills in English"
+        ],
+        "job_responsibilities": [
+          "Design, develop, and maintain complex PHP applications using Laravel framework",
+          "Write clean, maintainable, and efficient code following best practices",
+          "Optimize database queries and ensure high performance of MySQL databases",
+          "Collaborate with cross-functional teams to define and implement new features",
+          "Participate in code reviews and provide constructive feedback",
+          "Mentor junior developers and share knowledge with the team",
+          "Stay updated with the latest PHP and Laravel developments",
+          "Troubleshoot and resolve technical issues in production environments"
+        ],
+        "optional_skills": [
+          "Experience with AWS RDS and AWS Aurora",
+          "Familiarity with GitFlow workflow",
+          "Knowledge of microservices architecture",
+          "Experience with CI/CD pipelines"
+        ]
+      }
+    }
+  }
+}
+```
+
+---
+
+## Examples
+
+### Basic Job Description
+
+```javascript
+const { SharpApiJobDescriptionService, JobDescriptionParameters } = require('@sharpapi/sharpapi-node-job-description');
+
+const service = new SharpApiJobDescriptionService(process.env.SHARP_API_KEY);
+
+const params = new JobDescriptionParameters(
+  'Marketing Manager',
+  'Acme Corp',
+  '3-5 years',
+  "Bachelor's Degree in Marketing",
+  'Full-time',
+  ['Digital Marketing', 'SEO', 'Content Strategy'],
+  ['Google Analytics', 'HubSpot'],
+  'Canada',
+  false,
+  false,
+  'Professional',
+  null,
+  'English'
+);
+
+service.generateJobDescription(params)
+  .then(statusUrl => service.fetchResults(statusUrl))
+  .then(result => {
+    const jobDesc = result.getResultJson().result;
+    console.log('Position:', jobDesc.job_position);
+    console.log('\nDescription:', jobDesc.job_short_description);
+    console.log('\nRequirements:');
+    jobDesc.job_requirements.forEach((req, i) => console.log(`${i + 1}. ${req}`));
+  })
+  .catch(error => console.error('Generation failed:', error));
+```
+
+### Bulk Job Description Generation
+
+```javascript
+const service = new SharpApiJobDescriptionService(process.env.SHARP_API_KEY);
+
+const positions = [
+  { title: 'Frontend Developer', skills: ['React', 'TypeScript', 'CSS'] },
+  { title: 'Backend Developer', skills: ['Node.js', 'PostgreSQL', 'Docker'] },
+  { title: 'Full Stack Developer', skills: ['JavaScript', 'MongoDB', 'Express'] }
+];
+
+async function generateMultipleDescriptions(positions) {
+  const descriptions = [];
+
+  for (const position of positions) {
+    const params = new JobDescriptionParameters(
+      position.title,
+      'TechCorp',
+      '2+ years',
+      "Bachelor's Degree",
+      'Full-time',
+      position.skills,
+      [],
+      'United States',
+      true,
+      false,
+      'Professional',
+      null,
+      'English'
+    );
+
+    const statusUrl = await service.generateJobDescription(params);
+    const result = await service.fetchResults(statusUrl);
+    descriptions.push(result.getResultJson().result);
+  }
+
+  return descriptions;
+}
+
+const allDescriptions = await generateMultipleDescriptions(positions);
+console.log(`Generated ${allDescriptions.length} job descriptions`);
+```
+
+### Customized Job Description with Context
+
+```javascript
+const service = new SharpApiJobDescriptionService(process.env.SHARP_API_KEY);
+
+const params = new JobDescriptionParameters(
+  'DevOps Engineer',
+  'CloudTech Solutions',
+  '4+ years',
+  "Bachelor's in Computer Science",
+  'Full-time',
+  ['Kubernetes', 'AWS', 'Terraform', 'CI/CD'],
+  ['Prometheus', 'Grafana', 'Helm'],
+  'Germany',
+  true,
+  true,
+  'Professional',
+  'Must have experience with financial services industry and German language skills',
+  'English'
+);
+
+const statusUrl = await service.generateJobDescription(params);
+const result = await service.fetchResults(statusUrl);
+const jobDesc = result.getResultJson().result;
+
+// Format for posting
+console.log('='.repeat(60));
+console.log(`${jobDesc.job_position} at ${jobDesc.company_name}`);
+console.log('='.repeat(60));
+console.log('\n' + jobDesc.job_short_description);
+console.log('\n**Requirements:**');
+jobDesc.job_requirements.forEach(req => console.log(`• ${req}`));
+console.log('\n**Responsibilities:**');
+jobDesc.job_responsibilities.forEach(resp => console.log(`• ${resp}`));
+```
+
+---
+
+## Use Cases
+
+- **Job Postings**: Create compelling job descriptions for job boards
+- **Internal Recruitment**: Generate consistent job descriptions for internal positions
+- **Recruitment Agencies**: Quickly create professional job specs for clients
+- **Career Pages**: Populate company career sites with well-written descriptions
+- **ATS Integration**: Generate descriptions for Applicant Tracking Systems
+- **Job Description Templates**: Create standardized templates for similar roles
+- **Multi-language Hiring**: Generate descriptions in multiple languages
+
+---
+
+## API Endpoint
+
+**POST** `/hr/job_description`
+
+For detailed API specifications, refer to:
+- [Postman Documentation](https://documenter.getpostman.com/view/31106842/2sBXVeGsVR)
+- [Product Page](https://sharpapi.com/en/catalog/ai/hr-tech/job-description-generator)
+
+---
+
+## Related Packages
+
+- [@sharpapi/sharpapi-node-related-skills](https://www.npmjs.com/package/@sharpapi/sharpapi-node-related-skills) - Skills generation
+- [@sharpapi/sharpapi-node-related-job-positions](https://www.npmjs.com/package/@sharpapi/sharpapi-node-related-job-positions) - Related positions
+- [@sharpapi/sharpapi-node-parse-resume](https://www.npmjs.com/package/@sharpapi/sharpapi-node-parse-resume) - Resume parsing
+- [@sharpapi/sharpapi-node-client](https://www.npmjs.com/package/@sharpapi/sharpapi-node-client) - Full SharpAPI SDK
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.
+
+---
+
+## Support
+
+- **Documentation**: [SharpAPI.com Documentation](https://sharpapi.com/documentation)
+- **Issues**: [GitHub Issues](https://github.com/sharpapi/sharpapi-node-client/issues)
+- **Email**: contact@sharpapi.com
+
+---
+
+**Powered by [SharpAPI](https://sharpapi.com/) - AI-Powered API Workflow Automation**

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sharpapi/sharpapi-node-job-description",
+  "version": "1.0.0",
+  "description": "SharpAPI.com Node.js SDK for generating job descriptions",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "sharpapi",
+    "ai-powered",
+    "ai capabilities",
+    "api",
+    "ai api",
+    "api integration",
+    "artificial intelligence",
+    "natural language processing",
+    "restful api",
+    "nodejs",
+    "software development",
+    "hr tech",
+    "job description",
+    "job posting"
+  ],
+  "author": "Dawid Makowski <contact@sharpapi.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@sharpapi/sharpapi-node-core": "file:../sharpapi-node-core"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sharpapi/sharpapi-node-job-description.git"
+  }
+}

package/src/Dto/JobDescriptionParameters.js

@@ -0,0 +1,54 @@
+/**
+ * JobDescriptionParameters DTO
+ */
+class JobDescriptionParameters {
+  constructor(
+    name,
+    company_name = null,
+    minimum_work_experience = null,
+    minimum_education = null,
+    employment_type = null,
+    required_skills = null,
+    optional_skills = null,
+    country = null,
+    remote = null,
+    visa_sponsored = null,
+    voice_tone = null,
+    context = null,
+    language = null,
+  ) {
+    this.name = name;
+    this.company_name = company_name;
+    this.minimum_work_experience = minimum_work_experience;
+    this.minimum_education = minimum_education;
+    this.employment_type = employment_type;
+    this.required_skills = required_skills;
+    this.optional_skills = optional_skills;
+    this.country = country;
+    this.remote = remote;
+    this.visa_sponsored = visa_sponsored;
+    this.voice_tone = voice_tone;
+    this.context = context;
+    this.language = language;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      company_name: this.company_name,
+      minimum_work_experience: this.minimum_work_experience,
+      minimum_education: this.minimum_education,
+      employment_type: this.employment_type,
+      required_skills: this.required_skills,
+      optional_skills: this.optional_skills,
+      country: this.country,
+      remote: this.remote,
+      visa_sponsored: this.visa_sponsored,
+      voice_tone: this.voice_tone,
+      context: this.context,
+      language: this.language,
+    };
+  }
+}
+
+module.exports = { JobDescriptionParameters };

package/src/SharpApiJobDescriptionService.js

@@ -0,0 +1,26 @@
+const { SharpApiCoreService, SharpApiJobTypeEnum } = require('@sharpapi/sharpapi-node-core');
+const { JobDescriptionParameters } = require('./Dto/JobDescriptionParameters');
+
+/**
+ * Service for generating job descriptions using SharpAPI.com
+ */
+class SharpApiJobDescriptionService extends SharpApiCoreService {
+  /**
+   * Generates a job description based on a set of parameters
+   * provided via JobDescriptionParameters DTO object.
+   * This endpoint provides concise job details in the response format,
+   * including the short description, job requirements, and job responsibilities.
+   *
+   * Only the job position `name` parameter is required inside jobDescriptionParameters.
+   *
+   * @param {JobDescriptionParameters} jobDescriptionParameters
+   * @returns {Promise<string>} - The status URL.
+   */
+  async generateJobDescription(jobDescriptionParameters) {
+    const data = jobDescriptionParameters.toJSON();
+    const response = await this.makeRequest('POST', SharpApiJobTypeEnum.HR_JOB_DESCRIPTION.url, data);
+    return this.parseStatusUrl(response);
+  }
+}
+
+module.exports = { SharpApiJobDescriptionService, JobDescriptionParameters };

package/src/index.js

@@ -0,0 +1,7 @@
+// sharpapi-node-job-description/src/index.js
+const { SharpApiJobDescriptionService, JobDescriptionParameters } = require('./SharpApiJobDescriptionService');
+
+module.exports = {
+  SharpApiJobDescriptionService,
+  JobDescriptionParameters,
+};