vcf-to-json-converter 1.0.0 → 1.0.1

package/README.md

@@ -1,36 +1,91 @@
-# VCF to JSON Converter
+# vcf-to-json-converter
 
-A lightweight Node.js library and CLI tool to convert VCF (vCard) files to JSON format.
+[![npm version](https://badge.fury.io/js/vcf-to-json-converter.svg)](https://badge.fury.io/js/vcf-to-json-converter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/vcf-to-json-converter.svg)](https://nodejs.org/)
+[![Downloads](https://img.shields.io/npm/dm/vcf-to-json-converter.svg)](https://npmjs.org/package/vcf-to-json-converter)
+
+A lightweight, fast, and reliable Node.js library to convert VCF (vCard) files to structured JSON format with full CLI support.
+
+```javascript
+const { vcfToJsonFromFile } = require("vcf-to-json-converter");
+
+const contacts = vcfToJsonFromFile("./contacts.vcf");
+console.log(contacts);
+```
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Command Line Interface](#command-line-interface)
+  - [Programmatic Usage](#programmatic-usage)
+  - [TypeScript](#typescript)
+- [API Reference](#api-reference)
+- [Output Format](#output-format)
+- [Supported vCard Fields](#supported-vcard-fields)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Features
 
-- 📱 Convert VCF/vCard files to structured JSON
-- 🔧 Programmatic API for Node.js applications
-- 💻 Command-line interface for quick conversions
-- 🛡️ Robust error handling
-- 📊 Extracts comprehensive contact information
-- 🎯 TypeScript-friendly
+- **Complete VCF Support** - Convert VCF/vCard files (v2.1, v3.0, v4.0) to structured JSON
+- **Programmatic API** - Easy integration into Node.js applications
+- **CLI Tool** - Command-line interface for quick conversions
+- **Robust Error Handling** - Comprehensive error handling and validation
+- **Rich Data Extraction** - Extracts all contact information including photos, organizations, and notes
+- **TypeScript Ready** - Full TypeScript definitions included
+- **High Performance** - Efficiently processes large VCF files with multiple contacts
+- **Cross Platform** - Works on Windows, macOS, and Linux
+- **Zero Dependencies** - No external dependencies for maximum compatibility
+- **UTF-8 Support** - Handles international characters and emojis correctly
 
 ## Installation
 
-### Global Installation (for CLI usage)
+Using npm:
+
+```bash
+npm install vcf-to-json-converter
+```
+
+For global CLI usage:
 
 ```bash
 npm install -g vcf-to-json-converter
 ```
 
-### Local Installation (for programmatic usage)
+Using yarn:
 
 ```bash
-npm install vcf-to-json-converter
+yarn add vcf-to-json-converter
+```
+
+## Quick Start
+
+```bash
+# Install globally for CLI
+npm install -g vcf-to-json-converter
+
+# Convert a VCF file
+vcf-to-json contacts.vcf output.json
+```
+
+```javascript
+// Use in your Node.js project
+const { vcfToJsonFromFile } = require("vcf-to-json-converter");
+
+const contacts = vcfToJsonFromFile("./contacts.vcf");
+console.log(`Converted ${contacts.length} contacts`);
 ```
 
 ## Usage
 
 ### Command Line Interface
 
-Convert a VCF file to JSON:
-
 ```bash
 # Convert and display JSON in terminal
 vcf-to-json contacts.vcf
@@ -38,8 +93,12 @@ vcf-to-json contacts.vcf
 # Convert and save to file
 vcf-to-json contacts.vcf output.json
 
-# Convert with compact formatting
+# Convert with compact formatting (minified JSON)
 vcf-to-json contacts.vcf output.json --compact
+
+# Show help and version
+vcf-to-json --help
+vcf-to-json --version
 ```
 
 ### Programmatic Usage
@@ -51,57 +110,102 @@ const {
   saveJsonToFile,
 } = require("vcf-to-json-converter");
 
-// Convert VCF text content to JSON
+// Method 1: Convert VCF text content
 const vcfContent = `BEGIN:VCARD
-VERSION:2.1
+VERSION:3.0
 FN:John Doe
-TEL:+1234567890
-EMAIL:john@example.com
+N:Doe;John;;;
+TEL;TYPE=CELL:+1234567890
+EMAIL;TYPE=HOME:john@example.com
+ORG:ACME Corp
+TITLE:Software Engineer
 END:VCARD`;
 
 const contacts = vcfToJson(vcfContent);
-console.log(contacts);
+console.log("Parsed contacts:", contacts.length);
 
-// Convert VCF file to JSON
+// Method 2: Convert VCF file directly
 try {
   const contacts = vcfToJsonFromFile("./contacts.vcf");
   console.log(`Converted ${contacts.length} contacts`);
 
-  // Save to JSON file
-  saveJsonToFile(contacts, "./output.json");
+  // Save to JSON file with pretty formatting
+  saveJsonToFile(contacts, "./output.json", true);
+
+  // Access contact data
+  contacts.forEach((contact) => {
+    console.log(
+      `${contact.fullName}: ${contact.phones.length} phones, ${contact.emails.length} emails`
+    );
+  });
 } catch (error) {
   console.error("Conversion failed:", error.message);
 }
 ```
 
+### TypeScript
+
+```typescript
+import { vcfToJsonFromFile, Contact } from "vcf-to-json-converter";
+
+const contacts: Contact[] = vcfToJsonFromFile("./contacts.vcf");
+console.log(contacts);
+```
+
 ## API Reference
 
-### `vcfToJson(vcfText)`
+### `vcfToJson(vcfText: string): Contact[]`
 
 Converts VCF text content to JSON.
 
-- **Parameters:**
-  - `vcfText` (string): The VCF content as a string
-- **Returns:** Array of contact objects
-- **Throws:** Error if VCF content is invalid
+**Parameters:**
+
+- `vcfText` _(string)_: The VCF content as a string
+
+**Returns:** Array of contact objects
 
-### `vcfToJsonFromFile(filePath)`
+**Throws:** Error if VCF content is invalid
+
+**Example:**
+
+```javascript
+const contacts = vcfToJson("BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nEND:VCARD");
+```
+
+### `vcfToJsonFromFile(filePath: string): Contact[]`
 
 Converts a VCF file to JSON.
 
-- **Parameters:**
-  - `filePath` (string): Path to the VCF file
-- **Returns:** Array of contact objects
-- **Throws:** Error if file doesn't exist or is invalid
+**Parameters:**
+
+- `filePath` _(string)_: Path to the VCF file
+
+**Returns:** Array of contact objects
 
-### `saveJsonToFile(jsonData, outputPath, prettyPrint)`
+**Throws:** Error if file doesn't exist or is invalid
+
+**Example:**
+
+```javascript
+const contacts = vcfToJsonFromFile("./my-contacts.vcf");
+```
+
+### `saveJsonToFile(jsonData: Contact[], outputPath: string, prettyPrint?: boolean): void`
 
 Saves JSON data to a file.
 
-- **Parameters:**
-  - `jsonData` (Array): The JSON data to save
-  - `outputPath` (string): Path where to save the JSON file
-  - `prettyPrint` (boolean, optional): Whether to format JSON with indentation (default: true)
+**Parameters:**
+
+- `jsonData` _(Contact[])_: The JSON data to save
+- `outputPath` _(string)_: Path where to save the JSON file
+- `prettyPrint` _(boolean, optional)_: Whether to format JSON with indentation (default: true)
+
+**Example:**
+
+```javascript
+saveJsonToFile(contacts, "./output.json", true); // Pretty formatted
+saveJsonToFile(contacts, "./compact.json", false); // Minified
+```
 
 ## Output Format
 
@@ -174,6 +278,39 @@ contacts.forEach((contact) => {
 });
 ```
 
+### Advanced Usage with Error Handling
+
+```javascript
+const { vcfToJsonFromFile, saveJsonToFile } = require("vcf-to-json-converter");
+
+try {
+  // Convert VCF file
+  const contacts = vcfToJsonFromFile("./contacts.vcf");
+
+  // Filter contacts with email addresses
+  const contactsWithEmail = contacts.filter(
+    (contact) => contact.emails.length > 0
+  );
+
+  // Extract business contacts
+  const businessContacts = contacts.filter((contact) => contact.organization);
+
+  console.log(
+    `Total: ${contacts.length}, With Email: ${contactsWithEmail.length}, Business: ${businessContacts.length}`
+  );
+
+  // Save different formats
+  saveJsonToFile(contacts, "./all-contacts.json", true); // Pretty
+  saveJsonToFile(businessContacts, "./business-contacts.json", false); // Compact
+} catch (error) {
+  if (error.code === "ENOENT") {
+    console.error("File not found. Please check the file path.");
+  } else {
+    console.error("Conversion error:", error.message);
+  }
+}
+```
+
 ### Batch Processing
 
 ```javascript
@@ -190,13 +327,53 @@ vcfFiles.forEach((file) => {
     const contacts = vcfToJsonFromFile(path.join("./vcf-files", file));
     const outputFile = file.replace(".vcf", ".json");
     saveJsonToFile(contacts, path.join("./json-output", outputFile));
-    console.log(`✅ Converted ${file} (${contacts.length} contacts)`);
+    console.log(`Converted ${file} (${contacts.length} contacts)`);
   } catch (error) {
-    console.error(`❌ Failed to convert ${file}:`, error.message);
+    console.error(`Failed to convert ${file}:`, error.message);
   }
 });
 ```
 
+## Troubleshooting
+
+### Common Issues
+
+**File not found error:**
+
+```bash
+Error: ENOENT: no such file or directory
+```
+
+- Ensure the VCF file path is correct
+- Use absolute paths if relative paths don't work
+- Check file permissions
+
+**Invalid VCF format:**
+
+```bash
+Error: Invalid VCF format
+```
+
+- Ensure your file starts with `BEGIN:VCARD` and ends with `END:VCARD`
+- Check for corrupted or incomplete vCard entries
+- Validate the VCF file structure
+
+**Empty output:**
+
+- Check if the VCF file contains properly formatted vCard entries
+- Ensure the file encoding is UTF-8
+- Verify the VCF version is supported (v2.1, v3.0, v4.0)
+
+**CLI command not found:**
+
+```bash
+'vcf-to-json' is not recognized as an internal or external command
+```
+
+- Reinstall globally: `npm install -g vcf-to-json-converter`
+- Check your PATH environment variable
+- Try using `npx vcf-to-json-converter` instead
+
 ## CLI Examples
 
 ```bash
@@ -216,26 +393,65 @@ vcf-to-json contacts.vcf contacts.json --compact
 ## Requirements
 
 - Node.js 12.0.0 or higher
-- npm or yarn
+- npm 6.0.0 or higher
 
 ## Contributing
 
+We welcome contributions! Please follow these steps:
+
 1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/shubhanshurav/vcf-to-json.git
+cd vcf-to-json
+
+# Install dependencies (if any)
+npm install
+
+# Run tests
+npm test
+
+# Test CLI locally
+node index.js contacts.vcf
+```
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Author
 
-## Changelog
+**Shubhanshu Rao**
 
-### 1.0.0
+- GitHub: [@shubhanshurav](https://github.com/shubhanshurav)
+- Repository: [vcf-to-json](https://github.com/shubhanshurav/vcf-to-json)
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/vcf-to-json-converter)
+- [GitHub repository](https://github.com/shubhanshurav/vcf-to-json)
+- [Report Issues](https://github.com/shubhanshurav/vcf-to-json/issues)
+- [Changelog](https://github.com/shubhanshurav/vcf-to-json/blob/main/CHANGELOG.md)
+
+## Version History
+
+### v1.0.0 (Latest)
 
 - Initial release
-- CLI support
-- Comprehensive vCard field parsing
-- Error handling
-- TypeScript-friendly exports
+- CLI support with global installation
+- Comprehensive vCard field parsing (v2.1, v3.0, v4.0)
+- Robust error handling and validation
+- TypeScript definitions included
+- UTF-8 and international character support
+- Zero dependencies for maximum compatibility
+
+---
+
+**Star this repository if you find it helpful!**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vcf-to-json-converter",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A lightweight Node.js library to convert VCF (vCard) files to JSON format with CLI support",
   "license": "MIT",
   "author": "Shubhanshu Rao",
@@ -26,12 +26,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/your-username/vcf-to-json-converter"
+    "url": "https://github.com/shubhanshurav/vcf-to-json.git"
   },
   "bugs": {
-    "url": "https://github.com/your-username/vcf-to-json-converter/issues"
+    "url": "https://github.com/shubhanshurav/vcf-to-json.git/issues"
   },
-  "homepage": "https://github.com/your-username/vcf-to-json-converter#readme",
+  "homepage": "https://github.com/shubhanshurav/vcf-to-json#readme",
   "engines": {
     "node": ">=12.0.0"
   },