@vcard/vcard4-generator
=======================
[![CI Status][BUILD BADGE]][BUILD PAGE]

A library for generating [v4 vCards](https://datatracker.ietf.org/doc/html/rfc6350)

Heads Up!
---------
This is still very much a WIP project and is _**not**_ feature complete.

Install
-------
```sh-session
npm install @vcard/vcard4-generator
```

Usage
-----
```ts
import Vcard4Generator, { Vcard4GeneratorConfig } from '@vcard/vcard4-generator';

const config: Vcard4GeneratorConfig = {
    fn: 'Captain Awesome',
    email: 'hello@example.com',
    url: 'http://www.example.com/'
};
const vcard = new Vcard4Generator(config);

vcard.toString();
// >> BEGIN:VCARD
// >> VERSION:4.0
// >> EMAIL:hello@example.com
// >> FN:Captain Awesome
// >> URL:http://www.example.com/
// >> END:VCARD
```

Building
--------
From the monorepo root:

```sh-session
npx lerna --scope @vcard/vcard4-generator run build
```

Testing
-------
From the monorepo root:

```sh-session
npm test
```

To-Do
-----
- [ ] Properties
  - [x] `ADR`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `LABEL` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `GEO` Parameter
    - [x] `TZ` Parameter
    - [x] `ALTID` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
  - [x] `ANNIVERSARY`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `ALTID` Parameter
    - [x] `CALSCALE` Parameter _(for `date-and-or-time` type only)_
  - [x] `BDAY`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `ALTID` Parameter
    - [x] `CALSCALE` Parameter _(for `date-and-or-time` type only)_
    - [x] `LANGUAGE` Parameter _(for `text` type only)_
  - [x] `BEGIN`
    - [x] No Parameters
  - [x] `BIRTHPLACE` _(RFC6474)_
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `LANGUAGE` Parameter
  - [x] `CALADRURI`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `CALURI`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `CATEGORIES`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `ALTID` Parameter
    - [ ] Implement Constructor `Array` Argument Support
  - [x] `CLIENTPIDMAP`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] No Parameters
    - [x] No `VALUE` Parameter
    - [ ] Implement Constructor `Array` Argument Support
  - [x] `CONTACT-URI` _(RFC8605)_
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PREF` Parameter
  - [x] `DEATHDATE` _(RFC6474)_
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `CALSCALE` Parameter _(for `date-and-or-time` type only)_
    - [x] `LANGUAGE` Parameter _(for `text` type only)_
    - [x] `ALTID` Parameter
  - [x] `DEATHPLACE` _(RFC6474)_
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `ALTID` Parameter
  - [x] `EMAIL`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `END`
    - [x] No Parameters
  - [x] `EXPERTISE` _(RFC6715)_
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `LEVEL` Parameter
    - [x] `INDEX` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
  - [x] `FBURL`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `FN`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `TYPE` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `ALTID` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
  - [x] `GENDER`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [ ] Implement Constructor `Array` Argument Support
  - [x] `GEO`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `HOBBY` _(RFC6715)_
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `LEVEL` Parameter
    - [x] `INDEX` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
  - [x] `IMPP`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `INTEREST` _(RFC6715)_
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `LEVEL` Parameter
    - [x] `INDEX` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
  - [x] `KEY`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `MEDIATYPE` Parameter _(for `URI` type only)_
    - [x] `ALTID` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
  - [x] `KIND`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
  - [x] `LANG`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
  - [x] `LOGO`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `MEMBER`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `MEDIATYPE` Parameter
  - [x] `N`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `SORT-AS` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `ALTID` Parameter
  - [x] `NICKNAME`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `TYPE` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `ALTID` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
  - [x] `NOTE`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `ORG`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `SORT-AS` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
  - [x] `ORG-DIRECTORY` _(RFC6715)_
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `INDEX` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
  - [x] `PHOTO`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
    - [x] `PREF` Parameter
    - [x] `PID` Parameter
  - [x] `PRODID`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
  - [x] `RELATED`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `MEDIATYPE` Parameter _(for `URI` type only)_
    - [x] `LANGUAGE` Parameter _(for `text` type only)_
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
  - [x] `REV`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
  - [x] `ROLE`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `SOUND`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `SOURCE`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `MEDIATYPE` Parameter
  - [x] `TEL`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `MEDIATYPE` Parameter _(for `URI` type only)_
    - [x] `TYPE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
  - [x] `TITLE`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `LANGUAGE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `ALTID` Parameter
    - [x] `TYPE` Parameter
  - [x] `TZ`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `ALTID` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
  - [x] `UID`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
  - [x] `URL`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `PID` Parameter
    - [x] `PREF` Parameter
    - [x] `TYPE` Parameter
    - [x] `MEDIATYPE` Parameter
    - [x] `ALTID` Parameter
  - [x] `VERSION`
    - [x] No Parameters
  - [x] `XML`
    - [x] Line Folding
    - [x] Value Escaping
    - [x] `VALUE` Parameter
    - [x] `ALTID` Parameter
- [x] Implement Parameter Value Encoding as Specified in [RFC6868](https://datatracker.ietf.org/doc/html/rfc6868)

Reference
---------

### Property Cardinalities
Property cardinalities are indicated using the following notation,
which is based on ABNF (see [RFC5234], Section 3.6):

| Cardinality | Meaning                                          |
|:-----------:|--------------------------------------------------|
|      1      | Exactly one instance per vCard MUST be present.  |
|      *1     | Exactly one instance per vCard MAY be present.   |
|      1*     | One or more instances per vCard MUST be present. |
|      *      | One or more instances per vCard MAY be present.  |

Properties defined in a vCard instance may have multiple values
depending on the property cardinality.  The general rule for encoding
multi-valued properties is to simply create a new content line for
each value (including the property name).  However, it should be
noted that some value types support encoding multiple values in a
single content line by separating the values with a comma ",".  This
approach has been taken for several of the content types defined
below (date, time, integer, float).

### Property Parameters
A property can have attributes associated with it.  These "property
parameters" contain meta-information about the property or the
property value.  In some cases, the property parameter can be multi-
valued in which case the property parameter value elements are
separated by a COMMA (U+002C).

Property parameter value elements that contain the COLON (U+003A),
SEMICOLON (U+003B), or COMMA (U+002C) character separators MUST be
specified as quoted-string text values.  Property parameter values
MUST NOT contain the DQUOTE (U+0022) character.  The DQUOTE character
is used as a delimiter for parameter values that contain restricted
characters or URI text.

Applications MUST ignore x-param and iana-param values they don't
recognize.

### Property Value Escaping
Some properties may contain one or more values delimited by a COMMA
character (U+002C).  Therefore, a COMMA character in a value MUST be
escaped with a BACKSLASH character (U+005C), even for properties that
don't allow multiple instances (for consistency).

Some properties (e.g., N and ADR) comprise multiple fields delimited
by a SEMICOLON character (U+003B).  Therefore, a SEMICOLON in a field
of such a "compound" property MUST be escaped with a BACKSLASH
character.  SEMICOLON characters in non-compound properties MAY be
escaped.  On input, an escaped SEMICOLON character is never a field
separator.  An unescaped SEMICOLON character may be a field
separator, depending on the property in which it appears.

Furthermore, some fields of compound properties may contain a list of
values delimited by a COMMA character.  Therefore, a COMMA character
in one of a field's values MUST be escaped with a BACKSLASH
character, even for fields that don't allow multiple values (for
consistency).  Compound properties allowing multiple instances MUST
NOT be encoded in a single content line.

Finally, BACKSLASH characters in values MUST be escaped with a
BACKSLASH character.  NEWLINE (U+000A) characters in values MUST be
encoded by two characters: a BACKSLASH followed by either an 'n'
(U+006E) or an 'N' (U+004E).

In all other cases, escaping MUST NOT be used.

### Links
- [vCard Format Specification](https://datatracker.ietf.org/doc/html/rfc6350)
- [vCard KIND:application](https://datatracker.ietf.org/doc/html/rfc6473)
- [vCard Format Extensions: Place of Birth, Place and Date of Death](https://datatracker.ietf.org/doc/html/rfc6474/)
- [vCard Format Extensions: Representing vCard Extensions Defined by the Open Mobile Alliance (OMA) Converged Address Book (CAB) Group](https://datatracker.ietf.org/doc/html/rfc6715/)
- [Additional Data Related to an Emergency Call § vCard Parameter Value Registration](https://datatracker.ietf.org/doc/html/rfc7852/#section-11.7)
- [vCard Format Extensions: ICANN Extensions for the Registration Data Access Protocol (RDAP)](https://datatracker.ietf.org/doc/html/rfc8605/)
- [vCard Elements (IANA Protocol Registry)](http://www.iana.org/assignments/vcard-elements/vcard-elements.xhtml)

License
-------
The MIT License (Expat). See the [license file](LICENSE) for details.

[BUILD BADGE]: https://github.com/jbenner-radham/vcardjs/actions/workflows/ci.yaml/badge.svg
[BUILD PAGE]: https://github.com/jbenner-radham/vcardjs/actions/workflows/ci.yaml