@pipobscure/vcard 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Core type definitions for vCard v4 (RFC 6350)
+ */
+/** All value types defined in RFC 6350 section 4 */
+export type ValueType = 'text' | 'uri' | 'date' | 'time' | 'date-time' | 'date-and-or-time' | 'timestamp' | 'boolean' | 'integer' | 'float' | 'utc-offset' | 'language-tag';
+/** Well-known TYPE parameter values */
+export type TypeValue = 'work' | 'home' | 'voice' | 'fax' | 'cell' | 'video' | 'pager' | 'textphone' | 'text' | 'contact' | 'acquaintance' | 'friend' | 'met' | 'co-worker' | 'colleague' | 'co-resident' | 'neighbor' | 'child' | 'parent' | 'sibling' | 'spouse' | 'kin' | 'muse' | 'crush' | 'date' | 'sweetheart' | 'me' | 'agent' | 'emergency' | string;
+/** KIND property values */
+export type KindValue = 'individual' | 'group' | 'org' | 'location' | string;
+/** GENDER sex component */
+export type GenderSex = 'M' | 'F' | 'O' | 'N' | 'U' | '';
+/**
+ * Partial date representation (RFC 6350 section 4.3.1).
+ * Supports reduced accuracy: year-only, year-month, or full date.
+ * Also supports omitted year (month-day only) for birthdays where year is unknown.
+ */
+export interface PartialDate {
+    year?: number;
+    month?: number;
+    day?: number;
+}
+/** Time-of-day representation */
+export interface TimeValue {
+    hour?: number;
+    minute?: number;
+    second?: number;
+    /** UTC offset: '+HH:MM', '-HH:MM', or 'Z' */
+    utcOffset?: string;
+}
+/** Combined date-and-or-time value */
+export interface DateAndOrTime extends PartialDate, TimeValue {
+    hasTime: boolean;
+}
+/** Structured name (N property) — RFC 6350 section 6.2.2 */
+export interface StructuredName {
+    familyNames: string[];
+    givenNames: string[];
+    additionalNames: string[];
+    honorificPrefixes: string[];
+    honorificSuffixes: string[];
+}
+/** Postal address (ADR property) — RFC 6350 section 6.3.1 */
+export interface Address {
+    postOfficeBox: string;
+    extendedAddress: string;
+    streetAddress: string;
+    locality: string;
+    region: string;
+    postalCode: string;
+    countryName: string;
+}
+/** Organization (ORG property) — RFC 6350 section 6.6.4 */
+export interface Organization {
+    name: string;
+    units: string[];
+}
+/** Gender value — RFC 6350 section 6.2.7 */
+export interface Gender {
+    sex: GenderSex;
+    identity?: string;
+}
+/** CLIENTPIDMAP value — RFC 6350 section 6.7.7 */
+export interface ClientPidMap {
+    pid: number;
+    uri: string;
+}
+/** Geographic position — URI format: geo:lat,lon */
+export interface GeoCoordinates {
+    latitude: number;
+    longitude: number;
+}
+/** Raw parameter storage: parameter name → value or list of values */
+export type ParameterMap = Map<string, string | string[]>;
+/**
+ * A property as parsed from text, before type-specific value interpretation.
+ * Useful for round-tripping unknown properties.
+ */
+export interface RawProperty {
+    group?: string;
+    name: string;
+    parameters: ParameterMap;
+    value: string;
+}
+/** A validation error with context */
+export interface ValidationError {
+    property: string;
+    message: string;
+}
+/** Result of vCard validation */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core type definitions for vCard v4 (RFC 6350)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/vcard.d.ts

@@ -0,0 +1,177 @@
+/**
+ * VCard — the main vCard v4 container class (RFC 6350)
+ *
+ * Provides typed access to all RFC 6350 properties, plus methods for
+ * parsing and generating vCard text.
+ */
+import type { ValidationResult } from './types.js';
+import { Property, VCardError, FNProperty, NProperty, NicknameProperty, PhotoProperty, BDayProperty, AnniversaryProperty, GenderProperty, AdrProperty, TelProperty, EmailProperty, IMPPProperty, LangProperty, TZProperty, GeoProperty, TitleProperty, RoleProperty, LogoProperty, OrgProperty, MemberProperty, RelatedProperty, CategoriesProperty, NoteProperty, ProdIDProperty, RevProperty, SoundProperty, UIDProperty, ClientPidMapProperty, URLProperty, KeyProperty, FBURLProperty, CALADRURIProperty, CALURIProperty, KindProperty, XMLProperty, SourceProperty, UnknownProperty } from './property.js';
+import { type ParseWarning } from './parser.js';
+import { type GenerateOptions } from './generator.js';
+/**
+ * A vCard v4 object.
+ *
+ * Properties with cardinality `1*` are arrays that must have at least one
+ * element before generating. Properties with cardinality `*1` are single
+ * optional values. Properties with cardinality `*` are arrays.
+ *
+ * Usage:
+ * ```ts
+ * // Parse
+ * const [vcard] = VCard.parse(text);
+ *
+ * // Build
+ * const vcard = new VCard();
+ * vcard.fn.push(new FNProperty('Alice Example'));
+ * vcard.email.push(new EmailProperty('alice@example.com'));
+ * console.log(vcard.toString());
+ * ```
+ */
+export declare class VCard {
+    /** vCard version string (from parsing — always '4.0' when generating) */
+    parsedVersion: string;
+    /** Warnings accumulated during parsing */
+    parseWarnings: ParseWarning[];
+    /** Formatted Name — required, at least one (RFC 6350 §6.2.1) */
+    fn: FNProperty[];
+    /** Structured Name (RFC 6350 §6.2.2) */
+    n?: NProperty;
+    /** Birthday (RFC 6350 §6.2.5) */
+    bday?: BDayProperty;
+    /** Anniversary (RFC 6350 §6.2.6) */
+    anniversary?: AnniversaryProperty;
+    /** Gender (RFC 6350 §6.2.7) */
+    gender?: GenderProperty;
+    /** Product Identifier (RFC 6350 §6.7.3) */
+    prodid?: ProdIDProperty;
+    /** Revision timestamp (RFC 6350 §6.7.4) */
+    rev?: RevProperty;
+    /** Unique Identifier (RFC 6350 §6.7.6) */
+    uid?: UIDProperty;
+    /** Kind (RFC 6350 §6.1.4) */
+    kind?: KindProperty;
+    /** Nicknames (RFC 6350 §6.2.3) */
+    nickname: NicknameProperty[];
+    /** Photos (RFC 6350 §6.2.4) */
+    photo: PhotoProperty[];
+    /** Addresses (RFC 6350 §6.3.1) */
+    adr: AdrProperty[];
+    /** Telephone numbers (RFC 6350 §6.4.1) */
+    tel: TelProperty[];
+    /** Email addresses (RFC 6350 §6.4.2) */
+    email: EmailProperty[];
+    /** Instant Messaging (RFC 6350 §6.4.3) */
+    impp: IMPPProperty[];
+    /** Languages (RFC 6350 §6.4.4) */
+    lang: LangProperty[];
+    /** Time zones (RFC 6350 §6.5.1) */
+    tz: TZProperty[];
+    /** Geographic positions (RFC 6350 §6.5.2) */
+    geo: GeoProperty[];
+    /** Titles (RFC 6350 §6.6.1) */
+    title: TitleProperty[];
+    /** Roles (RFC 6350 §6.6.2) */
+    role: RoleProperty[];
+    /** Logos (RFC 6350 §6.6.3) */
+    logo: LogoProperty[];
+    /** Organizations (RFC 6350 §6.6.4) */
+    org: OrgProperty[];
+    /** Group members (RFC 6350 §6.6.5) */
+    member: MemberProperty[];
+    /** Related entities (RFC 6350 §6.6.6) */
+    related: RelatedProperty[];
+    /** Categories (RFC 6350 §6.7.1) */
+    categories: CategoriesProperty[];
+    /** Notes (RFC 6350 §6.7.2) */
+    note: NoteProperty[];
+    /** Sounds (RFC 6350 §6.7.5) */
+    sound: SoundProperty[];
+    /** Client PID maps (RFC 6350 §6.7.7) */
+    clientpidmap: ClientPidMapProperty[];
+    /** URLs (RFC 6350 §6.7.8) */
+    url: URLProperty[];
+    /** Public keys (RFC 6350 §6.8.1) */
+    key: KeyProperty[];
+    /** Free/Busy URLs (RFC 6350 §6.9.1) */
+    fburl: FBURLProperty[];
+    /** Calendar User Address URIs (RFC 6350 §6.9.2) */
+    caladruri: CALADRURIProperty[];
+    /** Calendar URIs (RFC 6350 §6.9.3) */
+    caluri: CALURIProperty[];
+    /** Source URIs (RFC 6350 §6.1.3) */
+    source: SourceProperty[];
+    /** XML properties (RFC 6350 §6.1.5) */
+    xml: XMLProperty[];
+    /** Unknown / extended / vendor properties (stored for round-tripping) */
+    extended: UnknownProperty[];
+    /**
+     * Parse one or more vCards from text.
+     * Tolerant: never throws, collects warnings instead.
+     *
+     * @returns Array of VCard instances (may be empty if input has no vCards)
+     */
+    static parse(text: string): VCard[];
+    /**
+     * Parse exactly one vCard from text.
+     * @throws Error if zero vCards are found
+     */
+    static parseOne(text: string): VCard;
+    /**
+     * Quick-create a vCard with just a formatted name.
+     * Useful for programmatic construction.
+     */
+    static create(fn: string): VCard;
+    /** Construct a VCard from a flat list of Property instances */
+    private static fromRaw;
+    /**
+     * Add a property to this vCard, routing it to the appropriate typed field.
+     * Unknown properties go to `extended`.
+     */
+    addProperty(prop: Property): void;
+    /**
+     * Get all properties as a flat array, in logical order.
+     * Includes all typed properties and extended properties.
+     */
+    allProperties(): Property[];
+    /**
+     * Get the primary (most preferred or first) formatted name string.
+     */
+    get displayName(): string;
+    /**
+     * Get the primary email address string.
+     */
+    get primaryEmail(): string | undefined;
+    /**
+     * Get the primary telephone string.
+     */
+    get primaryTel(): string | undefined;
+    /**
+     * Generate RFC 6350-compliant vCard text.
+     * Uses strict CRLF line endings and 75-octet line folding.
+     *
+     * @throws VCardError if the vCard is invalid (e.g. missing FN)
+     */
+    toString(options?: GenerateOptions): string;
+    /**
+     * Generate without validation (useful for partial/draft vCards).
+     * Use with caution — output may not be RFC-compliant.
+     */
+    toStringLenient(): string;
+    /**
+     * Validate this vCard against RFC 6350 requirements.
+     * Returns a result object rather than throwing.
+     */
+    validate(): ValidationResult;
+    /**
+     * Deep-clone by round-tripping through text serialization.
+     * Produces a clean v4 vCard from whatever version was parsed.
+     */
+    clone(): VCard;
+    /**
+     * Convert to a plain object suitable for JSON serialization (jCard-ish).
+     * This is a simplified representation, not full jCard (RFC 7095).
+     */
+    toJSON(): Record<string, unknown>;
+}
+export { VCardError };
+//# sourceMappingURL=vcard.d.ts.map

package/dist/vcard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcard.d.ts","sourceRoot":"","sources":["../src/vcard.ts"],"names":[],"mappings":"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"}