vcf-to-json-converter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubhanshu Rao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# VCF to JSON Converter
+
+A lightweight Node.js library and CLI tool to convert VCF (vCard) files to JSON format.
+
+## 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
+
+## Installation
+
+### Global Installation (for CLI usage)
+
+```bash
+npm install -g vcf-to-json-converter
+```
+
+### Local Installation (for programmatic usage)
+
+```bash
+npm install vcf-to-json-converter
+```
+
+## Usage
+
+### Command Line Interface
+
+Convert a VCF file to JSON:
+
+```bash
+# Convert and display JSON in terminal
+vcf-to-json contacts.vcf
+
+# Convert and save to file
+vcf-to-json contacts.vcf output.json
+
+# Convert with compact formatting
+vcf-to-json contacts.vcf output.json --compact
+```
+
+### Programmatic Usage
+
+```javascript
+const {
+  vcfToJson,
+  vcfToJsonFromFile,
+  saveJsonToFile,
+} = require("vcf-to-json-converter");
+
+// Convert VCF text content to JSON
+const vcfContent = `BEGIN:VCARD
+VERSION:2.1
+FN:John Doe
+TEL:+1234567890
+EMAIL:john@example.com
+END:VCARD`;
+
+const contacts = vcfToJson(vcfContent);
+console.log(contacts);
+
+// Convert VCF file to JSON
+try {
+  const contacts = vcfToJsonFromFile("./contacts.vcf");
+  console.log(`Converted ${contacts.length} contacts`);
+
+  // Save to JSON file
+  saveJsonToFile(contacts, "./output.json");
+} catch (error) {
+  console.error("Conversion failed:", error.message);
+}
+```
+
+## API Reference
+
+### `vcfToJson(vcfText)`
+
+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
+
+### `vcfToJsonFromFile(filePath)`
+
+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
+
+### `saveJsonToFile(jsonData, outputPath, prettyPrint)`
+
+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)
+
+## Output Format
+
+Each contact is converted to the following JSON structure:
+
+```json
+{
+  "fullName": "John Doe",
+  "firstName": "John",
+  "lastName": "Doe",
+  "phones": [
+    {
+      "value": "+1234567890",
+      "type": "CELL"
+    }
+  ],
+  "emails": [
+    {
+      "value": "john@example.com",
+      "type": "HOME"
+    }
+  ],
+  "organization": "ACME Corp",
+  "title": "Software Engineer",
+  "note": "Important contact",
+  "photo": "",
+  "url": "",
+  "raw": {
+    /* Original parsed vCard object */
+  }
+}
+```
+
+## Supported vCard Fields
+
+- **Name:** Full name, first name, last name
+- **Phone:** Multiple phone numbers with types
+- **Email:** Multiple email addresses with types
+- **Organization:** Company/organization name
+- **Title:** Job title
+- **Note:** Notes/comments
+- **Photo:** Photo data (base64)
+- **URL:** Website URLs
+- **Raw:** Complete original vCard data
+
+## Error Handling
+
+The library provides comprehensive error handling for:
+
+- Invalid file paths
+- Missing files
+- Permission errors
+- Malformed VCF content
+- Invalid input parameters
+
+## Examples
+
+### Basic Conversion
+
+```javascript
+const { vcfToJsonFromFile } = require("vcf-to-json-converter");
+
+const contacts = vcfToJsonFromFile("my-contacts.vcf");
+console.log(`Found ${contacts.length} contacts`);
+
+contacts.forEach((contact) => {
+  console.log(
+    `${contact.fullName}: ${contact.phones.map((p) => p.value).join(", ")}`
+  );
+});
+```
+
+### Batch Processing
+
+```javascript
+const fs = require("fs");
+const path = require("path");
+const { vcfToJsonFromFile, saveJsonToFile } = require("vcf-to-json-converter");
+
+const vcfFiles = fs
+  .readdirSync("./vcf-files")
+  .filter((f) => f.endsWith(".vcf"));
+
+vcfFiles.forEach((file) => {
+  try {
+    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)`);
+  } catch (error) {
+    console.error(`❌ Failed to convert ${file}:`, error.message);
+  }
+});
+```
+
+## CLI Examples
+
+```bash
+# Show help
+vcf-to-json --help
+
+# Convert single file
+vcf-to-json contacts.vcf
+
+# Convert and save to specific file
+vcf-to-json contacts.vcf my-contacts.json
+
+# Compact output
+vcf-to-json contacts.vcf contacts.json --compact
+```
+
+## Requirements
+
+- Node.js 12.0.0 or higher
+- npm or yarn
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Changelog
+
+### 1.0.0
+
+- Initial release
+- CLI support
+- Comprehensive vCard field parsing
+- Error handling
+- TypeScript-friendly exports

package/index.d.ts

@@ -0,0 +1,32 @@
+export interface Phone {
+  value: string;
+  type: string;
+}
+
+export interface Email {
+  value: string;
+  type: string;
+}
+
+export interface Contact {
+  fullName: string;
+  firstName: string;
+  lastName: string;
+  phones: Phone[];
+  emails: Email[];
+  organization: string;
+  title: string;
+  note: string;
+  photo: string;
+  url: string;
+  raw: any;
+}
+
+export declare function vcfToJson(vcfText: string): Contact[];
+export declare function vcfToJsonFromFile(filePath: string): Contact[];
+export declare function saveJsonToFile(
+  jsonData: Contact[],
+  outputPath: string,
+  prettyPrint?: boolean
+): void;
+export declare function cli(): void;

package/index.js

@@ -0,0 +1,252 @@
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Manual VCF parser that properly extracts contact information
+ * @param {string} vcfText - The VCF content as string
+ * @returns {Array} Array of contact objects
+ */
+function parseVCF(vcfText) {
+  const contacts = [];
+
+  // Split by BEGIN:VCARD to handle multiple contacts
+  const vCards = vcfText.split("BEGIN:VCARD").filter((card) => card.trim());
+
+  for (const vCard of vCards) {
+    const lines = vCard.split(/\r?\n/).filter((line) => line.trim());
+
+    const contact = {
+      fullName: "",
+      firstName: "",
+      lastName: "",
+      phones: [],
+      emails: [],
+      organization: "",
+      title: "",
+      note: "",
+      photo: "",
+      url: "",
+      raw: vCard, // Store original vCard text
+    };
+
+    for (const line of lines) {
+      // Parse FN (Formatted Name) - supports UTF-8/Hindi
+      if (line.startsWith("FN:")) {
+        contact.fullName = line.substring(3).trim();
+      }
+
+      // Parse N (Name) for first and last name
+      if (line.startsWith("N:")) {
+        const nameParts = line.substring(2).split(";");
+        // Format: Last;First;Middle;Prefix;Suffix
+        contact.lastName = (nameParts[0] || "").trim();
+        contact.firstName = (nameParts[1] || "").trim();
+
+        // If fullName is empty, construct it from first and last name
+        if (!contact.fullName) {
+          contact.fullName = `${contact.firstName} ${contact.lastName}`.trim();
+        }
+      }
+
+      // Parse TEL (Phone)
+      if (line.startsWith("TEL")) {
+        const phoneMatch = line.match(/:([\d\s\-+()]+)/);
+        if (phoneMatch) {
+          // Extract phone type from the TEL line
+          let phoneType = "unknown";
+          if (line.includes("CELL")) phoneType = "mobile";
+          else if (line.includes("HOME")) phoneType = "home";
+          else if (line.includes("WORK")) phoneType = "work";
+          else if (line.includes("VOICE")) phoneType = "voice";
+          else if (line.includes("PREF")) phoneType = "primary";
+
+          contact.phones.push({
+            value: phoneMatch[1].trim(),
+            type: phoneType,
+          });
+        }
+      }
+
+      // Parse EMAIL
+      if (line.startsWith("EMAIL")) {
+        const emailMatch = line.match(/:(.+)/);
+        if (emailMatch) {
+          // Extract email type from the EMAIL line
+          let emailType = "unknown";
+          if (line.includes("HOME")) emailType = "home";
+          else if (line.includes("WORK")) emailType = "work";
+          else if (line.includes("PREF")) emailType = "primary";
+
+          contact.emails.push({
+            value: emailMatch[1].trim(),
+            type: emailType,
+          });
+        }
+      }
+
+      // Parse ORG (Organization)
+      if (line.startsWith("ORG:")) {
+        contact.organization = line.substring(4).trim();
+      }
+
+      // Parse TITLE
+      if (line.startsWith("TITLE:")) {
+        contact.title = line.substring(6).trim();
+      }
+
+      // Parse NOTE
+      if (line.startsWith("NOTE:")) {
+        contact.note = line.substring(5).trim();
+      }
+
+      // Parse URL
+      if (line.startsWith("URL:")) {
+        contact.url = line.substring(4).trim();
+      }
+
+      // Parse PHOTO (basic support)
+      if (line.startsWith("PHOTO:")) {
+        contact.photo = line.substring(6).trim();
+      }
+    }
+
+    // Only add contact if it has meaningful data
+    if (
+      contact.fullName ||
+      contact.firstName ||
+      contact.lastName ||
+      contact.phones.length > 0
+    ) {
+      contacts.push(contact);
+    }
+  }
+
+  return contacts;
+}
+
+/**
+ * Convert VCF text content to JSON
+ * @param {string} vcfText - The VCF content as string
+ * @returns {Array} Array of contact objects
+ */
+function vcfToJson(vcfText) {
+  if (!vcfText || typeof vcfText !== "string") {
+    throw new Error("Invalid VCF content. Expected non-empty string.");
+  }
+
+  try {
+    return parseVCF(vcfText);
+  } catch (error) {
+    throw new Error(`Failed to parse VCF content: ${error.message}`);
+  }
+}
+
+/**
+ * Convert VCF file to JSON
+ * @param {string} filePath - Path to the VCF file
+ * @returns {Array} Array of contact objects
+ */
+function vcfToJsonFromFile(filePath) {
+  if (!filePath || typeof filePath !== "string") {
+    throw new Error("File path is required and must be a string.");
+  }
+
+  try {
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+
+    const vcfText = fs.readFileSync(filePath, "utf8");
+    return vcfToJson(vcfText);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    if (error.code === "EACCES") {
+      throw new Error(`Permission denied: ${filePath}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Save JSON data to file
+ * @param {Array} jsonData - The JSON data to save
+ * @param {string} outputPath - Path to save the JSON file
+ * @param {boolean} prettyPrint - Whether to format JSON with indentation
+ */
+function saveJsonToFile(jsonData, outputPath, prettyPrint = true) {
+  if (!outputPath || typeof outputPath !== "string") {
+    throw new Error("Output path is required and must be a string.");
+  }
+
+  try {
+    const jsonString = prettyPrint
+      ? JSON.stringify(jsonData, null, 2)
+      : JSON.stringify(jsonData);
+
+    fs.writeFileSync(outputPath, jsonString, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to save JSON file: ${error.message}`);
+  }
+}
+
+/**
+ * CLI function to convert VCF to JSON
+ */
+function cli() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    console.log(`
+VCF to JSON Converter
+
+Usage:
+  vcf-to-json <input.vcf> [output.json] [options]
+
+Options:
+  --compact, -c    Output compact JSON (no formatting)
+  --help, -h       Show this help message
+
+Examples:
+  vcf-to-json contacts.vcf
+  vcf-to-json contacts.vcf output.json
+  vcf-to-json contacts.vcf output.json --compact
+`);
+    return;
+  }
+
+  const inputFile = args[0];
+  const outputFile = args[1] || inputFile.replace(/\.vcf$/i, ".json");
+  const compact = args.includes("--compact") || args.includes("-c");
+
+  try {
+    console.log(`Converting ${inputFile} to JSON...`);
+    const jsonData = vcfToJsonFromFile(inputFile);
+
+    if (args[1]) {
+      saveJsonToFile(jsonData, outputFile, !compact);
+      console.log(
+        `✅ Converted ${jsonData.length} contacts and saved to ${outputFile}`
+      );
+    } else {
+      console.log(JSON.stringify(jsonData, null, compact ? 0 : 2));
+    }
+  } catch (error) {
+    console.error(`❌ Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Export functions
+module.exports = {
+  vcfToJson,
+  vcfToJsonFromFile,
+  saveJsonToFile,
+  cli,
+};
+
+// If this file is run directly, execute CLI
+if (require.main === module) {
+  cli();
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "vcf-to-json-converter",
+  "version": "1.0.0",
+  "description": "A lightweight Node.js library to convert VCF (vCard) files to JSON format with CLI support",
+  "license": "MIT",
+  "author": "Shubhanshu Rao",
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "vcf-to-json": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test.js",
+    "demo": "node index.js contacts.vcf"
+  },
+  "keywords": [
+    "vcf",
+    "vcard",
+    "json",
+    "converter",
+    "contacts",
+    "parser",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/vcf-to-json-converter"
+  },
+  "bugs": {
+    "url": "https://github.com/your-username/vcf-to-json-converter/issues"
+  },
+  "homepage": "https://github.com/your-username/vcf-to-json-converter#readme",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "devDependencies": {}
+}