@sdxc/jscontact

Read, validate and write RFC 9553 JSContact Cards, and convert them to and from vCard and jCard.

JSContact is the JSON counterpart of vCard. Cards are written at version 2.0 (RFC 9982), where uid is optional. The model is the JSON itself, so a parsed Card serializes back unchanged, and unknown and vendor properties are kept.

Installation#

npm add @sdxc/jscontact remix

Validation runs on remix/data-schema, and fallible functions return a Result from @sdxc/result, which installs alongside.

Usage#

Read and validate a Card#

import { parse } from "@sdxc/jscontact";
import { isFailure } from "@sdxc/result";

let parsed = parse(await request.text());
if (isFailure(parsed)) throw parsed.error; // JSContactParseError, with .issues and their paths

parsed.data.name?.full; // "Joe User"

Read a Card in another language#

import { localize } from "@sdxc/jscontact";

let french = localize(card, "fr"); // the "fr" localization applied, or the Card unchanged

Convert vCard and jCard#

import { fromVCard, parseVCard, readJCard, stringifyVCard, toVCard } from "@sdxc/jscontact/vcard";
import { isSuccess } from "@sdxc/result";

let cards = parseVCard(await file.text());
if (isSuccess(cards)) cards.data.map(fromVCard); // JSContact.Card[]

let jcard = readJCard(entity.vcardArray); // a jCard, such as an RDAP entity's
if (isSuccess(jcard)) fromVCard(jcard.data);

let text = stringifyVCard(toVCard(card)); // text/vcard

Conversion follows RFC 9555: each map entry becomes a property carrying its key in PROP-ID, localizations become LANGUAGE alternatives tied by ALTID, and a vCard property with no counterpart is kept in vCardProps. Anything a vCard property cannot carry travels in JSPROP, so a Card converted to vCard and back is unchanged.

Command line#

bunx @sdxc/jscontact --help

With @sdxc/kit installed, sdxc pkg jscontact … runs the same command line, using the version your project installs.

convert reads JSContact, vCard or jCard (detected, or named with --from) from a file or stdin and writes the format --to names:

bunx @sdxc/jscontact convert contact.vcf --to jscontact

validate checks Cards against RFC 9553, printing every problem and exiting 1 when one is invalid; --json prints { valid, issues }:

bunx @sdxc/jscontact validate card.json

API#

parse(source: unknown): Result<JSContact.Card, JSContactParseError>#

Validates JSON text or an already-parsed value against RFC 9553 and RFC 9982, including case variants of registered names, which the RFC makes invalid. CARD_SCHEMA is the schema itself.

stringify(card: JSContact.Card): string#

Compact JSON, the body of a MEDIA_TYPE (application/jscontact+json;version=2.0) response.

localize(card: JSContact.Card, language: string): Result<JSContact.Card, PatchError>#

The Card with its localization for language applied, matched case-insensitively.

applyPatch(object, patch): Result<object, PatchError>#

Applies a PatchObject to a copy, all or nothing.

isId(value), isUTCDateTime(value)#

The Id alphabet, and the single valid spelling of a UTCDateTime.

@sdxc/jscontact/vcard#

• parseVCard(text) reads one or more vCards; stringifyVCard(cards) writes them folded at 75 octets with CRLF endings.

• readJCard(json) and writeJCard(card) read and write RFC 7095 jCard. A malformed jCard property is skipped rather than failing the card.

• fromVCard(card) and toVCard(card) convert between that card and a JSContact Card.

• detectFormat(text) answers "jscontact", "vcard" or "jcard" from the text alone, or null.

• VCARD_MEDIA_TYPE and JCARD_MEDIA_TYPE are text/vcard;charset=utf-8 and application/vcard+json, ready for a Content-Type header.

Types#

JSContact.Card and every object it holds (Name, Address, Phone, …) live under the JSContact namespace; VCard, VCardProperty and JCard are exported from ./vcard.

Where to go next

• Offer and import contact cards
• Use a package from the terminal