@leigh-chr/vcard-utils

TypeScript utilities for parsing and generating vCard files according to RFC 6350.

Features

• Parse vCard 3.0 and 4.0 files into typed JavaScript objects
• Generate valid vCard files from contact data
• Full support for common vCard properties
• Multiple phone, email, and address support
• Photo and organization handling
• Zero external dependencies
• TypeScript-first with full type definitions

Installation

npm install @leigh-chr/vcard-utils
# or
bun add @leigh-chr/vcard-utils
# or
pnpm add @leigh-chr/vcard-utils

Quick Start

import { parseVCardFile, generateVCardFile } from '@leigh-chr/vcard-utils';

// Parse a vCard file
const { contacts, errors } = parseVCardFile(vcardContent);
console.log(contacts[0].fullName);
console.log(contacts[0].emails);

// Generate a vCard file
const vcard = generateVCardFile({
  contacts: [{
    fullName: 'John Doe',
    emails: [{ value: '[email protected]', type: 'work' }],
    phones: [{ value: '+1234567890', type: 'cell' }],
  }]
});

API Reference

Parser

import { parseVCardFile } from '@leigh-chr/vcard-utils';

const result = parseVCardFile(vcardString);
// Returns: { contacts: ParsedContact[], errors: string[] }

Generator

import { generateVCardFile } from '@leigh-chr/vcard-utils';

const vcard = generateVCardFile({
  contacts: [{
    fullName: 'Jane Smith',
    firstName: 'Jane',
    lastName: 'Smith',
    nickname: 'Janie',
    emails: [
      { value: '[email protected]', type: 'work' },
      { value: '[email protected]', type: 'home' },
    ],
    phones: [
      { value: '+1234567890', type: 'cell' },
      { value: '+0987654321', type: 'work' },
    ],
    addresses: [{
      street: '123 Main St',
      city: 'New York',
      state: 'NY',
      postalCode: '10001',
      country: 'USA',
      type: 'home',
    }],
    organization: 'Acme Corp',
    title: 'Software Engineer',
    birthday: new Date('1990-01-15'),
    note: 'Met at conference',
    photo: 'https://example.com/photo.jpg',
  }]
});

Types

import type {
  ParsedContact,
  ParsedEmail,
  ParsedPhone,
  ParsedAddress,
  ParsedIM,
  ParsedRelation,
  ContactInput,
  GeneratorOptions,
  ParseResult,
  PhoneTypeValue,
  EmailTypeValue,
  AddressTypeValue,
  ContactKindValue,
  GenderValue,
} from '@leigh-chr/vcard-utils';

ParsedContact

interface ParsedContact {
  uid?: string;
  fullName: string;
  firstName?: string;
  lastName?: string;
  middleName?: string;
  prefix?: string;
  suffix?: string;
  nickname?: string;
  emails: ParsedEmail[];
  phones: ParsedPhone[];
  addresses: ParsedAddress[];
  organization?: string;
  title?: string;
  department?: string;
  birthday?: Date;
  anniversary?: Date;
  note?: string;
  photo?: string;
  url?: string;
  imAccounts: ParsedIM[];
  relations: ParsedRelation[];
  categories?: string[];
  gender?: GenderValue;
  kind?: ContactKindValue;
}

ParsedEmail

interface ParsedEmail {
  value: string;
  type?: EmailTypeValue; // 'home' | 'work' | 'other'
  primary?: boolean;
}

ParsedPhone

interface ParsedPhone {
  value: string;
  type?: PhoneTypeValue; // 'cell' | 'home' | 'work' | 'fax' | 'pager' | 'other'
  primary?: boolean;
}

ParsedAddress

interface ParsedAddress {
  street?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
  type?: AddressTypeValue; // 'home' | 'work' | 'other'
  primary?: boolean;
}

Subpath Exports

For tree-shaking, you can import specific modules:

import { parseVCardFile } from '@leigh-chr/vcard-utils/parser';
import { generateVCardFile } from '@leigh-chr/vcard-utils/generator';

License

AGPL-3.0 - See LICENSE for details.

Contributing

Contributions are welcome! Please see our Contributing Guide.